qmax

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

Beyond the annotations (which already declare readOnly/idempotent/non-destructive), the description discloses the fill model ('decisions on an hour's close, filled at the next hour's open'), that no-trade hours are untradeable, that the history lacks order-book depth so large sizes are optimistic, and the flat QSwap fee risk. That is exactly the kind of behavioral 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?

Dense but front-loaded — capability and reported outputs come first, mechanics and strategy semantics follow, caveats last. Every sentence carries information, though the strategy paragraph is a long run-on that could be split.

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 still tells the agent what the result contains and explicitly points to the 'warnings' field. For a read-only, non-persistent simulation tool this covers everything needed to call and interpret 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 coverage is 60%, and the description compensates well: it defines the three strategy types and ties bandPct, fractionPct, lookbackHours and cooldownHours to the 'bands' logic and amountQu/everyHours to 'dca'. Only 'range' is left to self-explanatory enum values.

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 ('Replays a strategy over real hourly trade data with the venues' real fees') and enumerates the exact outputs (final value, return, buy-and-hold comparison, max drawdown, fees, trades). It is unmistakably a simulation tool, distinct in kind from the get_* siblings, though it never names an alternative to disambiguate.

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 strongly implied: the strategy enum is expanded so an agent knows which strategy to pick and which parameters each one consumes, and the 'READ warnings' instruction steers interpretation. There is no explicit when-not-to-use or named alternative, 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 declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context beyond them: the tool signs nothing and sends nothing, steps must be signed and broadcast by the caller, unused QU is refunded, maxOutlayQu caps total outlay, and signing a step moves real funds. This is exactly the extra context the schema and annotations cannot 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?

Front-loads the core purpose in the first sentence, then organizes step detail and the spending-limit warning in a readable sequence. It is fairly long, but nearly every sentence carries distinct information; only minor phrasing 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?

There is no output schema, so the description carries the full burden of explaining return values, and it does so in detail: kind, description, destination, inputType, amountQu (with refund semantics), payloadBase64, and maxOutlayQu. Combined with the step ordering and signing model, an agent has everything needed to invoke and consume 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 coverage is 50%, so the schema documents asset and holdings_qx/holdings_qswap. The description clarifies that holdings parameters are sell-only and drive step planning, adding real meaning. However slippage_bps and qty remain undocumented in both places, so it does not fully compensate for the coverage 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?

States a specific verb and resource: it quotes an order and returns the exact unsigned transactions a wallet must sign, in order. It also draws a clear line against sibling quote tools by emphasizing that QMax signs nothing and sends nothing. An agent can tell this is a transaction-planning tool, not a price-quote 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?

Gives concrete usage conditions: pass holdings_qx/holdings_qswap for sells, buys need no holdings, and check maxOutlayQu against a spending limit BEFORE signing. It lacks an explicit 'use this instead of qmax_get_quote / qmax_swap_quote when...' routing statement, so it's clear context without full alternative 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/idempotent/openWorld annotations, it discloses that the loop is two separate transactions so the second leg can fill worse, that the result is a snapshot and not a guarantee, and that a found result may be billed 50 QU to the caller's key. These are exactly the execution-risk and cost facts an agent needs and that structured fields 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?

Three tight sentences, front-loaded with the core action and return value, then the caveats and the billing note. Each sentence carries distinct information, with only mild compression in the parenthetical billing clause.

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 still conveys the shape of the result (most profitable size or null) and the key limitations and cost. It stops short of describing what a successful result object contains, but for a single-value search return that is 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 each of the four parameters is already documented in the schema (including the asset lookup pointer to qmax_list_assets). The description adds no format, unit, or interaction guidance beyond that, 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?

Precise verb and resource: searches live and at full depth for a buy-one-market/sell-the-other loop net of every venue fee and returns the most profitable size or null. This is clearly distinct from sibling tools like qmax_swap_quote and qmax_get_quote, which only price a single venue.

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 states a real precondition - only assets listed on both markets can produce a result - which implies when the tool applies, but it never names an alternative or says when not to call it (e.g., when you only need one venue's price). Usage is implied rather than spelled out.

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 read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds real behavioral context beyond that: the archive begins April 2026 (about six months), a candle exists only where trades occurred, and the response can be truncated or unavailable (truncated?, available? flags). Some of the depth limit is duplicated in the range/interval schema text, which keeps this from 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?

The opening sentence is front-loaded with the payload contents, and the explicit return-shape block is justified because no output schema exists. The prose is dense but every clause carries information; only the 'Returns:' literal 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?

With no output schema, the description carries the full burden and does so: it enumerates every returned field, explains the gap semantics, the historical boundary, the 5,000-candle cap and the truncation flags. An agent has everything needed to call this and interpret the result.

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 unit semantics the schema never states ('Prices are QU per unit'), clarifies that candles are 'a minute wide at the finest', and notes the 24h volume is aggregated across both markets regardless of the venue parameter.

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 concrete verb+resource: OHLCV candles plus QU volume, units and trade count, built from every trade on QX and QSwap. That is specific and unambiguous. It does not, however, differentiate itself from the near-duplicate siblings qmax_get_price_history and qmax_get_tape, so an agent cannot tell from the text alone which of the three to reach for.

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 explicit when-to-use guidance and no named alternative, despite qmax_get_price_history and qmax_get_tape sitting in the same family. The only orienting remark is interpretive ('a gap means no trades'), which explains output rather than telling the agent when this tool is the right choice.

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 and non-destructive, so the safety profile is covered. The description adds real value beyond that: 'Direction is the taker's side' defines the semantics, and 'partial' is true while the server is still loading' discloses an asynchronous completion state an agent would otherwise misread as final data.

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 dense sentences with zero filler, front-loading the measured quantities before the scope and the partial-load caveat. Every clause carries information not present in the 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?

There is no output schema, so the description correctly enumerates what comes back (volumes, trade counts, net pressure, partial flag) plus the sign convention. The only material gap is the unexplained venue parameter; otherwise an agent can call and interpret this tool from the description alone.

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 only 33%, so the description must compensate. It does explain window semantics ('last hour or 24 hours') and that asset is optional ('one asset or the whole market'), but venue — an enum with two values — is never mentioned in either the schema or the description, leaving that parameter opaque.

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 (buy/sell volume in QU and units, trade counts, net pressure) with scope (last hour or 24 hours, one asset or whole market) and even defines the sign convention. It is distinguishable from siblings like qmax_get_tape or qmax_get_order_book, though it never explicitly names an alternative.

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 implied by the scope clauses ('for one asset or the whole market', window choices) rather than stated as when-to-use guidance. There is no exclusion or explicit pointer to a sibling tool for related questions such as raw trades.

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 read-only/idempotent safety profile, but the description goes well beyond them: it defines each flag, explains the wash-suspected detection mechanism and its volume/count asymmetry, warns that absence of the flag is not proof of a clean market, and states the score is a non-advisory automated estimate. That is unusually rich disclosure of method, error semantics, and limitations.

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 output definition, then layered with flag semantics and caveats; nearly every sentence carries distinct information. The parenthetical explanations and long final sentence make it dense, but nothing reads as 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 carries the burden of describing the return values and does so fully (score, grade, flags, ranked plain-English reasons), plus interpretation caveats and the batch-mode behavior. An agent has everything needed to call and interpret 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 coverage is 100% and the single optional parameter is already documented in the schema, so the baseline is 3; the description adds value by spelling out that omitting 'asset' returns grade, score, flags and top reason for every asset, which clarifies the batch mode's output shape rather than just restating the field.

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 the exact artifact produced (a 0–100 score and A–E grade) and the three data sources it is computed from (QX order book, QSwap pool, six months of trades), which cleanly separates it from siblings like qmax_get_order_book or qmax_get_flow that return raw data rather than a derived grade.

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 usage guidance for the one parameter ('omit asset to get every asset's grade in one call') and frames expected outcomes ('many assets grade D or E... that is information, not an error'), which prevents an agent from misreading results. It never names an alternative tool or an explicit when-not-to-use condition, so it stops 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that values are read live from the contract, which is useful, but it also spends a sentence on the 100,000 QU cost of adding/removing liquidity — behavior of a different operation, not this read tool.

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 what is read, followed by the usage cue, then a short note. Mostly tight, but the flat-fee sentence is tangential to a read-only reserve lookup and does not earn its place here.

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 tool with no output schema, the description states the data source and the fields returned, which is enough for an agent to call it correctly. The missing piece is differentiation from qmax_pool_detail and other pool-related siblings.

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?

There is a single parameter with 100% schema description coverage, and the schema already documents the asset symbol format and points to qmax_list_assets. The description adds no syntax or format detail beyond the schema, so 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 names a specific resource (a single QSwap pool) and enumerates what is returned: reserves in QU and tokens, total liquidity units, and price, read from the contract. It is clear what the tool does, though it never distinguishes itself from near-siblings like qmax_pool_detail or qmax_list_pools.

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 offers one usage cue — check pool depth before discussing liquidity provision — but gives no explicit when-not conditions and does not name the sibling to use for the related tasks (qmax_pool_detail, qmax_get_liquidity_positions). The guidance is implied rather than routing.

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 readOnlyHint/idempotent annotations, it discloses non-obvious behavior: the 'complete' flag meaning partial reads, that 'earnedFeesQu' is already embedded in the removal payout, and that values are pool-price estimates that can diverge from thin-market sale prices. This is exactly the surplus 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?

The purpose and return fields are front-loaded in the first sentence, with caveats (complete, earnedFeesQu, estimate) following. It is denser than strictly necessary but nearly every clause adds usable detail rather than 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 compensates by naming the returned fields, explaining the partial-read flag, and warning about estimate semantics. An agent has everything needed to call it and interpret results 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 coverage is 100% with a single documented 'identity' parameter, so the schema already does the heavy lifting and baseline 3 applies. The description adds only a marginal note that any 60-letter identity works because the data is public chain data.

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 precise verb+resource+scope: 'Every QSwap pool a wallet has liquidity in', then enumerates the returned quantities (liquidity units, share, removal payout, QU value). An agent can immediately distinguish this wallet-position tool from pool/asset listing siblings like qmax_list_pools or qmax_pool_detail.

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 bounds the tool's role: read-only, and 'adding or removing liquidity is done in the QMax app with a wallet; this tool never builds or signs one.' That cleanly excludes mutation use cases, though it does not name a specific alternative sibling tool for the write path.

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, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context by describing what is computed and returned (outward cumulative aggregation, price-impact simulation for 0.1%–5% trades). It stays silent on any fusion of the two data sources or freshness, which keeps it below 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?

Two sentences, front-loaded with the returned content and closed with the usage trigger. Dense but every clause is informative. Slightly heavy parenthetical nesting keeps it from 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?

There is no output schema, so the description carries the full burden of explaining return values, and it does so thoroughly for both the order book and the QSwap pool, including reserve, price, and price-impact figures. An agent has what it needs to call and interpret this 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%, so both 'asset' (with a pointer to qmax_list_assets) and 'levels' are documented in the schema. The description reinforces that output is grouped by price from the best outward, which lightly informs 'levels', but adds no new parameter semantics. 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 clearly states the resource and contents: the QX order book (grouped by price, cumulative size/cost, best bid/ask, spread) and the QSwap pool (reserves, price, price impact). It is a specific and informative statement of what the tool retrieves. It does not explicitly name the sibling it differs from (e.g., qmax_get_liquidity_pool, qmax_pool_detail), 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 it to judge depth before sizing an order' gives a concrete when-to-use context. However, it names no alternative or exclusion condition, so an agent has no explicit routing guidance versus the other pool/book siblings like qmax_swap_quote or qmax_get_quote.

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 safety (readOnly, idempotent, non-destructive), but the description adds substantial data-semantics context not in any structured field: points before 'recordedSince' are hourly volume-weighted averages rebuilt from trades (marked src 'trades') while later points are recorded roughly every 10 minutes. That provenance detail directly affects how an agent interprets values.

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 dense sentences front-loading the return format, then the alternative tool. Every clause carries information — no filler, no restating of the name or 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?

With no output schema, the description must carry the return shape, and it does: point fields (ms timestamp, price in QU, bid/ask/pool price for recent points) plus the 'src' marker and sampling cadence. Nothing essential for correct invocation or interpretation 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 schema already documents both 'asset' and 'range' (including the 'all' ~six-month meaning). The description explains what the returned points mean but adds no extra meaning about manipulating the parameters, 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?

Starts with a specific verb+resource+scope: the asset's price over time returned as timestamped points in QU, including bid/ask/pool price for recent points. It is clearly distinguishable from qmax_get_candles, which it names as the OHLC/volume alternative.

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 routes the agent to qmax_get_candles 'for OHLC and volume', which is a concrete alternative-selection rule. It does not state when-not to use this tool (e.g. prefer candles for charting), so it falls just short of full 5-level 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 readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds genuinely new behavioral context: it restates that nothing is placed, warns the quote is a snapshot that goes stale, and advises re-quoting before acting.

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 in the first sentence, then covers returns and the staleness caveat. The return enumeration is long but each item is informative; little waste overall.

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 thoroughly (total, average price, legs, single-market comparisons, savings line, warnings). Combined with annotations covering safety, an agent has enough to call it correctly; only explicit sibling routing guidance 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 80%, so the schema already documents qty, asset, split, and slippage_bps. The description adds the unit convention ('All amounts are QU; quantities are whole units') and implies split's effect, which is marginal added value on top of an already well-documented 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?

States a specific verb (prices an order, finds the cheapest route) and a concrete resource (QX order book + QSwap pool), and distinguishes its scope from single-venue siblings by describing cross-venue routing and splitting. An agent can tell this is the multi-venue routing quote without opening any 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?

Usage is implied rather than stated: 'Nothing is placed' and 're-quote before acting' suggest it is a pre-trade preview, but no sibling (e.g. qmax_swap_quote) is named as an alternative and no explicit when/when-not condition is given. Adequate but leaves routing choice 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?

Beyond the readOnly/idempotent annotations, it discloses the data source (public Qubic archive), the async workflow (first call returns status 'working' with progress, poll every 30-60s until 'ready'), the run time (a minute or two), the six-hour cache retention, cost (free), and an honest limitation ('shows who sold and what they paid, not why').

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 7-day scope and dense with genuinely useful content, though the single run-on sentence packs the polling procedure and caveats together and could be broken up for scanning.

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 still conveys what comes back (sellers, holding durations, purchase price, above/below verdict, plain-language reading) and fully covers the multi-call async lifecycle, so an agent has everything needed to invoke and interpret 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% for the single asset parameter, and the schema already supplies the example and the pointer to qmax_list_assets. The description adds no format or constraint detail 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?

The description names a specific verb+resource (sellers of an asset over the last 7 days on QX/QSwap) and adds distinguishing detail — FIFO cost-basis matching and above/below-purchase reads — that separates it from siblings like qmax_get_tape or qmax_get_wallet_ledger.

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 context for use (last-7-day seller history on Qubic venues) and crucial operational guidance for the async read, but it does not name alternatives or explicitly state when a different sibling (e.g. wallet_ledger) would be the better pick.

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 and openWorld. The description adds real behavioral value on top: the source is in-memory hence cheap to poll, direction is the TAKER's side (a subtle semantic that changes interpretation), and each row carries a transaction hash. No rate limits or pagination behavior are mentioned.

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 what the feed contains, then direction semantics, then continuation and cost. Every sentence carries information, though the explicit field enumeration is slightly list-like 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?

With no output schema, the description does the work of describing return fields, the flow24h aggregate and the latestId cursor, which is exactly what an agent needs. It leaves minor gaps around what 'limit' bounds in the combined two-market feed and how the 24h flow is bucketed.

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 50%: 'asset' and 'since' are documented in the schema, and the description usefully reinforces 'since' as the latestId continuation token. 'limit' and 'venue' get no prose explanation, though the venue enum is self-describing. This is the baseline 3 given the mixed coverage.

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+resource: the most recent trades across QX and QSwap in one newest-first feed, with the exact columns returned. That is clearly separable from siblings like qmax_get_candles, qmax_get_order_book and qmax_get_flow (though the embedded 'flow24h' summary is a useful distinguishing note).

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 operating context: served from memory so cheap to poll, and pass 'latestId' back as 'since' to fetch only newer rows — a precise incremental-polling recipe. It never names an alternative tool or states when not to use this one, so it stops 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?

Goes well beyond the annotations (which cover read-only/idempotent/open-world) by disclosing that results are ESTIMATED, that the archive has a June 2026 gap, that pre-window/transferred units have unknown cost and distort profit, that QSwap liquidity moves surface as transfers, and that thin-market mid/pool pricing can mislead. It also flags latency/cost and a non-tax-advice caveat.

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 capability and return shape before the caveats, and every sentence carries substantive information. It is dense rather than padded, though the caveat block is long enough to be slightly heavy.

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 takes on the burden of enumerating return fields and the warnings/truncated flags. It also covers accuracy limits and cost, leaving only the undocumented `days` parameter as a 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?

The description adds meaning for `identity` ('any 60-letter identity works'), but schema coverage is 50% and the `days` window parameter (default 180, 1-365) is never explained in either schema or description. The 'before the window' phrasing gestures at a time window without mapping it to the parameter.

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+resource: 'Every QX and QSwap buy and sell a wallet made', naming the wallet-ledger scope explicitly. It then enumerates the exact outputs (price, QU net of fees, running position, average-cost realized profit, unrealized P&L), which cleanly separates it from siblings like qmax_get_tape, qmax_get_flow, and qmax_get_liquidity_positions.

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 context for when to reach for it (reconstructing a wallet's trade history and cost-basis P&L) and practical guidance ('ask once and keep the answer' due to cost). It does not name an alternative sibling or state when not to use it, so it stops short of full routing.

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, non-destructive safety, so the bar is lower. The description adds ordering behavior (most liquid first), venue semantics, and the meaning of each returned field, including that prices are per unit in QU — useful context beyond the 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?

Front-loads purpose, then usage, then return shape in three tight sentences with no filler. The return-shape sentence is dense but earns its place given the absence of an 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?

With no output schema, the description compensates by spelling out the return structure and field meanings, and annotations cover safety. Missing only minor details like pagination or default-limit behavior, which the schema partially covers.

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 schema already documents limit, query, and category. The description only implies the symbol-search behavior of 'query' and category meanings ('contract' shares vs 'token') already enumerated in the schema, adding little beyond that baseline.

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 specific verbs (lists/searches) and the exact resource (assets trading on QX and/or QSwap), and clarifies it operates across two venues. An agent can distinguish this inventory/search tool from siblings like qmax_get_quote or qmax_get_order_book 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?

'Use this first to find the right asset symbol' gives explicit workflow positioning before the quote/trade tools. It also explains a downstream condition (assets on both venues can be split for a better price), though it doesn't name a specific sibling to use afterward.

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 (readOnly, idempotent, non-destructive, openWorld), but the description adds real behavioral context: the 0.192% LP fee take rate, the trailing-estimate caveat that past fees don't predict future fees, and that wash-traded volume is flagged in pool notes. That is meaningful domain context an agent could not get from the structured fields.

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 scope ('Every QSwap liquidity pool') followed by the field list, then a single caveat sentence. Dense but every clause carries information; the only weakness is the tightly packed field enumeration.

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 must describe return contents, and it does so by naming each metric plus the fee-rate and wash-trading caveats. Adequate for a read-only listing tool; only the parameter-level behavior (sorting, limiting) is left unstated.

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 carries the burden. It partially compensates: the three named metrics (TVL, trailing volume, fee APR) map onto the sort enum values, and 'over the window' hints at the window parameter. However, the sort and limit parameters are never explicitly explained, and the 7d/30d enum values go unmentioned.

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+resource (listing every QSwap liquidity pool) and enumerates the returned dimensions (TVL, trailing volume, fee APR, price change, impermanent loss), which distinguishes it from qmax_pool_detail. It never names a sibling explicitly, so the differentiation is by implication rather than direct routing.

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 explains what comes back but says nothing about when to call this versus qmax_pool_detail, qmax_get_liquidity_pool, or qmax_list_assets. There are no conditions, prerequisites, or exclusions — usage must be inferred from the name alone.

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, so the safety bar is low, and the description adds real context beyond them: what the estimate contains (fees per day, per 30 days, IL at three price-move levels) and the flat 100,000 QU cost assumption for adding/removing liquidity. It does not mention rate limits, freshness of the underlying data, or what happens when position_qu is omitted.

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, purpose front-loaded before the estimate details and the cost caveat. Dense but every clause carries information; 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 must describe returns and largely does (fees per day, per 30 days, IL at 10/25/50%), plus a cost assumption. Gaps remain: the window parameter's effect on the estimate and the default behaviour when position_qu is not supplied are unaddressed.

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 33%, so the description must carry weight; it does define position_qu as 'the QU value of both sides together', which the schema leaves undocumented. However, the window parameter (7d/30d enum, default 7d) is never explained, and it is unclear from the description whether position_qu is optional or what the output looks like without 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?

States a specific verb+resource: 'one pool's numbers explained' plus a deposit-size estimate of daily/30-day fees and impermanent loss at 10/25/50% price moves. That is a clear, distinctive capability that separates it from generic siblings like qmax_get_liquidity_pool or qmax_list_pools, though it never names a sibling to route against.

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: you gather the estimate when you have a deposit size (position_qu) in mind. There is no explicit when-to-use/when-not guidance, no statement of prerequisites, and no pointer to an alternative tool for a plain pool lookup.

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/idempotent annotations, it discloses non-trivial behavior: the wallet must hold 'upfrontQu' before leg 1, minOutQty is only guaranteed if price doesn't move past the slippage limit, and the swap is never atomic so a completed leg 1 with a failed leg 2 leaves the user holding QU. This is exactly the kind of risk context annotations cannot 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?

It is front-loaded with the core mechanism before the caveats, and every sentence carries real information (fees, guarantees, failure mode). It is on the longer side, but the density is justified rather than padded.

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 correctly explains the return values (both quotes, upfrontQu, expectedOutQty, minOutQty, warnings) and the atomicity caveat. For a five-parameter planning tool with no output contract elsewhere, nothing an agent needs 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 80%, so the schema already documents 'to', 'qty', 'from', and 'compare' well. The description reinforces the sell/buy direction of 'from'/'to' and references a slippage limit, but it adds no syntax or format detail beyond the schema, particularly for the undocumented slippage_bps. Baseline 3 fits.

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?

It states a specific verb and resource ('Plans swapping one token for another as two linked trades') and explains the two-leg mechanism (sell 'from' for QU, then buy 'to' with the QU). It also distinguishes itself from the sibling qmax_get_quote by noting QU is not a swap leg.

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 clearly says when to use it (token-to-token swaps routed across QX and QSwap) and gives one explicit alternative ('QU itself is not a swap leg (use qmax_get_quote)'). It does not address how it relates to other plan-related siblings like qmax_build_plan or qmax_backtest, so it stops short of full alternatives coverage.

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 the safe-read profile (readOnly, idempotent, openWorld, non-destructive), yet the description goes well beyond them: it defines the sign convention, labels the output an upper bound rather than a profit, and names the specific omissions that make it one (hourly averages, QX bid-ask spread, inter-transaction delay). That is exactly the kind of behavioral context an agent needs to avoid misinterpreting the result.

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, no filler, and the core measurement is front-loaded before the caveats and the return-shape note. Dense but every clause carries information; the return-field list at the end is slightly list-like but useful given no 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?

For an analytical tool with no output schema, the description compensates by naming the returned keys (bothVenues, breakEvenPct, points, summary, note) and by scoping the metric's limitations. The remaining gap is routing: nothing tells the agent when to pick this over qmax_check_arbitrage or qmax_backtest.

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 67%; the description adds real meaning for reference_qu by explaining it is the trade size used to derive the break-even gap (the schema only says 'Trade size in QU'). 'Hour by hour' also conveys the time granularity behind the range parameter. The range enum itself is left without added semantics in either place.

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 measurement: the hourly price gap between QX and QSwap for a given asset, with an explicit sign convention ('positive = QSwap dearer') and a defined threshold ('wider than the trading costs for a trade of reference_qu'). It is clearly a historical/analytical measurement rather than a live quote, though it never names the sibling it is meant to be used instead of (e.g. qmax_check_arbitrage), so differentiation is implicit.

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 framing as an 'UPPER BOUND on arbitrage, not a profit' implies this is for research/backtesting rather than live execution, but there is no explicit when-to-use, when-not-to-use, or named alternative such as qmax_check_arbitrage or qmax_backtest. The agent must infer the intended context from the caveats.

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