The Spice Melange Trading Desk

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

Annotations already cover the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely new context: the token travels only in a header to the store and is never persisted, and the connector holds no keys or funds. It still omits failure behavior (unmatched digest, unpaid order) and any retry/rate-limit notes.

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 mode logic is front-loaded and well ordered, which is exactly right. However, two sentences of transactional legal boilerplate ('not financial advice', 'all sales final') do not help an agent select or invoke the tool and dilute an otherwise tight definition.

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 carry return-value burden and handles part of it (signed download link plus add-ons; status plus a fresh link once paid). For a payment-verification tool it still leaves error and partial-payment outcomes unspecified, so it is strong but not fully complete.

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 a baseline of 3 applies, but the description goes further by explaining the semantic role of 'digest' as the mode switch rather than just 'a Sui transaction digest'. The 'plus add-ons' phrase slightly enriches the intended output of the digest path.

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 ('verify your on-chain payment for an order and get the signed download link') and clearly splits the tool into two modes based on the presence of the digest parameter. An agent can tell it apart from create_template_order or list_templates without opening the schema.

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

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

Gives an explicit conditional: use with a digest to verify a payment and mint the download link, omit it to poll order status. It does not name siblings (e.g. create_template_order) or state when this tool should *not* be used, so it falls short of a full when/when-not/alternatives statement.

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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, but the description adds materially beyond them: nothing is charged by this call, the private token is shown once and must be kept secret, the payee and exact amount must be paid from the caller's own wallet before expiry, and the connector never holds keys or funds. This is exactly the kind of safety and side-effect context a write-path tool needs.

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 most important facts are front-loaded: purpose, then return values, then payment obligations and limits. It runs long as a single paragraph, and the legal boilerplate ('no returns promised. All sales final...') is lower-value filler for an agent selecting a tool, but nothing is genuinely redundant.

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 fully (order id, PRIVATE token shown once, payee, exact USDC amount, expiry). Combined with payment mechanics, custody disclaimer, and rate limits, an agent has everything needed to call and follow up 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%, with sku documented as sourced from list_templates and email as an optional receipt address. The description adds no parameter-level detail (no mention of the sku pattern or the email field), so it neither compensates for nor extends the schema. Baseline 3 applies when the schema carries parameters.

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

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

The opening sentence states a specific verb and resource ('Create a store order for one template') and immediately follows with the concrete artifacts returned (order id, private token, payee, exact Sui USDC amount). This is clearly distinguishable from siblings like list_templates (enumeration) and check_template_order (status lookup).

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 lays out the usage flow well: create the order, then send the exact USDC amount from your own wallet before expiry, implying check_template_order as a subsequent step. It also states the rate limit context ('a few orders per client per hour'). It stops short of explicitly naming an alternative tool or stating when NOT to use it, 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.

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, yet the description goes well beyond them: free tier of 100 calls/day per client, 0.002 USDC per call thereafter, prepaid batches of ~0.01 USDC, a payment-required response carrying an exact amount and payment_token, and a data-staleness disclaimer. That is exactly the extra behavioral context (cost, rate limits, auth flow, reliability) an agent needs.

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 core purpose and the input-token-vs-DEEP comparison before the disclaimers and pricing mechanics. The payment-tier sentence is long and detail-dense, but every clause (amount, batch size, payment_token) earns its place for a paid tool.

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

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

For a 6-parameter, no-output-schema tool the description covers purpose, the two fee outputs being compared, the maker/taker dimension, and the full paid-tier flow. It stops short of describing the response shape (e.g. whether both fee figures are returned), which matters slightly more given there is no output schema.

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 83% so the baseline is 3, and the description adds genuine meaning on top: it explains the maker/taker role as the fee-mode switch and frames payment_tx/payment_token as post-free-tier inputs tied to the payment-required response. It does not add format or syntax detail for qty/price beyond the schema, so it stops short of a 5.

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 (estimate) and resource (DeepBook fee for a fill of qty at price), and states the exact computation basis: input-token rate x 1.25 versus DEEP base rate, using live on-chain rates and the DEEP_USDC mid. This is unmistakably distinct from siblings like get_mid_price or get_pool_params, so an agent can select it 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?

Usage is implied (fee estimation for a prospective fill) and the payment-tier conditions are spelled out, but there is no explicit when-to-use versus alternatives, nor any stated exclusions such as 'do not use for actual order pricing' beyond the education-only disclaimer. Adequate but leaves the routing decision 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 declare readOnlyHint, idempotentHint and destructiveHint=false, but the description adds real context beyond them: a concrete rate-limit/cost model (100 calls/day free, then 0.002 USDC per call, prepaid in ~0.01 USDC batches), the payment-required handshake, and an explicit data-quality caveat ('may be delayed or wrong'). It stops short of describing pagination or truncation behavior at the 200-limit cap.

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 core purpose and scope are front-loaded and the paragraph wastes little space on the mechanics an agent needs. The 'Education/information only; not financial advice' clause is boilerplate that does not help tool selection and slightly bloats an otherwise dense single paragraph.

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 carries the return-shape burden, listing the fields and newest-first ordering, and it covers the payment workflow end to end. What is missing is behavior at the limit boundary (truncation/pagination) and the meaning of the hours window.

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 71%, so most fields are documented, yet the description still adds meaning: it clarifies the maker/taker framing behind the role parameter and the exact pricing/batching mechanics behind payment_tx and payment_token, which the schema only sketches. It adds nothing for hours or limit, which remain undocumented defaults.

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

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

The description names a specific verb and resource ('Fills (OrderFilled) where a given DeepBook BalanceManager was the maker or the taker in one pool') and specifies return contents (time, side, price, qty, fee, tx) plus ordering ('newest first'). The balance-manager-plus-pool scoping cleanly separates it from sibling market-wide tools like get_recent_trades or get_order_book.

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 scope (fills tied to one BalanceManager in one pool) but there is no explicit when-to-use / when-not guidance and no sibling is named as an alternative. The one genuinely directive element is the two-step payment flow (free tier first, then payment_tx/payment_token after the payment-required response), which is a retrieval precondition rather than a use-vs-alternatives rule.

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?

Adds substantial behavior beyond the readOnly/idempotent/openWorld annotations: the data source URL, ed25519 signature verification against a pinned release key, fail-closed behavior on signature mismatch, and explicit content constraints (no orders, no monetary sizes, no promised returns, not financial advice). The fail-closed semantics are exactly the kind of trait annotations cannot express.

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?

A single dense sentence plus two short disclaimer clauses, front-loaded with the source and payload contents. Every clause carries information, though the disclaimer tail could be trimmed slightly.

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 enumerating the returned content categories and stating the integrity guarantee and failure mode. Nothing an agent needs to call and interpret this tool correctly appears to be missing.

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

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

The tool takes zero parameters, so the schema has nothing to document and the description needs to add no parameter meaning. Baseline 4 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 and enumerates its payload (focus pools, ladder windows, rung guidance, rebalance ranges, projects, lessons), which lets an agent distinguish it immediately from the market-data siblings like get_ohlcv or get_order_book. The verb is implicit in the tool name but the purpose is unambiguous.

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

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

The description establishes context ('guidance only: no orders, no sizes in money, no promised returns') but never states when to call it versus alternatives, nor any prerequisites for invoking it. Usage is only implied by the content summary.

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 structurally. The description adds genuinely new context beyond that: the data is public and 'may be delayed or wrong', which tells the agent how much to trust the result. The 'education only / not financial advice' line is boilerplate but not contradictory.

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

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

Three short sentences, front-loaded with what is returned and followed by when to use it. It is well-sized, though the legal disclaimer sentence is padding that does not help the agent invoke the tool.

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

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

For a zero-parameter read-only status endpoint with no output schema, the description is nearly complete: it says what comes back, when to call it, and how reliable the data is. Annotations carry the safety profile. Nothing essential is missing, though return-value structure is only sketched rather than detailed.

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 no parameter semantics to document and the baseline is 4. The parenthetical list of returned fields (status, latest checkpoint, server time) is a useful stand-in for the absent output schema.

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

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

The description names a specific resource (the public DeepBook indexer) and enumerates what it reports: status, latest checkpoint, server time. That is much more concrete than a generic 'health check'. It does not explicitly differentiate itself from the many market-data siblings, keeping it 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 when data looks stale' gives a clear triggering condition for invoking the tool, so the agent knows when it is relevant. There is no explicit when-not guidance or reference to an alternative diagnostic tool, but for a single-purpose status endpoint the context is sufficient.

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

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

Beyond the annotations (which cover readOnly/idempotent/openWorld safety), it discloses rate limits (100 calls/day), per-call cost (0.002 USDC), the prepaid batch model, and a data-quality caveat ('may be delayed or wrong'). That is substantive operational context an agent cannot 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?

The return payload is front-loaded in the first sentence, followed by a compact compliance line and a pricing/access sentence. The 'not financial advice' line is boilerplate but short and relevant; overall density is good with no redundancy between sentences.

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

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

With no output schema, the description correctly enumerates the return fields (bid, ask, mid, spread abs/bps, last trade), and it also covers cost, access tiers, and data reliability. An agent has everything needed to call this and interpret the result without opening anything else.

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 pool, payment_tx, and payment_token are already fully documented in the schema, including format examples and the plb_ pattern. The description's mention of payment_token and the payment-required response restates schema content rather than adding new semantics, 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 ('get') and enumerates exactly what is returned: best bid, best ask, mid price, spread in absolute and bps, plus last trade price, scoped to a DeepBook pool. That precision separates it cleanly from siblings like get_order_book (full depth) and get_pool_stats (pool-level metrics).

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 implies the tool is for top-of-book price information and states the tiered access model (free 100 calls/day, then paid via payment_token), but never explicitly says when to prefer this over get_order_book or get_recent_trades. The 'only after the free tier' phrasing is conditional guidance tied to a parameter rather than a use-case routing statement.

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), and the description adds substantial context beyond that: data 'may be delayed or wrong', exact rate limit (100 calls/day per client), per-call price, prepaid batch size, and the payment-required handshake that yields a payment_token. That is exactly the operational behavior an agent needs to handle the paid path.

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 capability, then intervals, then units, then the operating constraints — a sensible order. The boilerplate disclaimer ('Education/information only; not financial advice') is padding for an agent, but everything else earns its place.

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

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

For a 7-parameter tool with no output schema, the description covers ordering, granularity, units, rate limits, and the full paid-retry flow. It does not describe the shape of each candle record, but OHLCV is a well-known format and the key semantics (ordering, units) are given.

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 86%, so the baseline is 3 and the schema already documents pool format, limit range, and timestamps. The description adds value the schema does not: it ties interval choices to candle granularity, clarifies that results are oldest-first (disambiguating start_time/end_time ordering), states volume is in the base asset, and explains the relationship between payment_token and payment_tx.

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?

Names the exact resource (OHLCV candles for a DeepBook pool), the ordering (oldest first), the supported intervals, and the volume denomination (base asset). This is unmistakably distinct from siblings like get_volume, get_recent_trades, and get_order_book, which return different data shapes.

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 guidance is implied through the payment flow: free 100 calls/day then 0.002 USDC, with payment_tx/payment_token required only after the free tier — that tells the agent when those params become relevant. However, the description never says when to prefer this over get_volume or get_recent_trades, so the alternative-selection guidance is absent.

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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: data may be delayed or wrong, a free tier of 100 calls/day, then 0.002 USDC per call prepaid in ~0.01 USDC batches, and that the payment-required response carries an exact amount and payment_token. It does not explain error/retry behavior beyond the payment path.

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?

One dense paragraph, front-loaded with the core capability before the pricing/payment detail. The 'Education/information only; not financial advice' clause does not aid tool selection but is a defensible compliance note, so only minor waste.

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

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

With no output schema, the description does state what is returned (per-side price levels plus cumulative base-quantity and quote-notional liquidity) and explains the payment path. It is nearly complete, missing only error/failure semantics beyond the payment-required response.

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 all five parameters including pool format, levels range, and the payment_token/payment_tx flow. The description restates 'top N price levels' and '±X% of mid' but adds no syntax or format 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?

States a specific resource and scope: 'Order book for a DeepBook pool: top N price levels per side and cumulative liquidity (base qty and quote notional) within ±X% of mid.' This clearly distinguishes it from siblings like get_mid_price, get_recent_trades, and get_volume, though it does not name them.

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 frames the tool as 'Education/information only; not financial advice' and notes data may be delayed, which implies when it is appropriate to use, but it never says when to choose this over siblings such as get_mid_price or get_pool_stats. Usage is left to inference from the purpose statement.

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, the description discloses the GraphQL-to-indexer fallback path, the staleness and correctness caveat ('may be delayed or wrong'), and concrete rate-limit and pricing behavior including the exact free-tier threshold, per-call cost, prepaid batch size, and the fact that the payment-required response supplies the exact amount and payment_token. That is unusually rich behavioral context.

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

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

The substantive answer (what fields, how fetched, fallback) is front-loaded before the compliance and billing sentences, and no sentence is redundant. The 'Education/information only; not financial advice' clause is boilerplate, but it is a single short clause rather than padding.

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 telling the agent what comes back, and it does so by enumerating the returned field groups. Combined with the fallback behavior and the billing/payment flow for repeat calls, an agent has everything needed to invoke it correctly without further documentation.

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 already 100%, so the pool format (BASE_QUOTE, case-insensitive, '/' or '-' accepted) is fully documented in the schema. The description still adds value by explaining the conditional lifecycle of payment_tx and payment_token — they only apply 'after the free tier' and are only obtainable from the payment-required response — which clarifies when those two optional params are actually required.

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 the resource (a DeepBook pool's parameters) and enumerates exactly which fields it returns — fees, DEEP stake requirement, tick/lot/min size, whitelist/stable flags, vault balances — which is far more than a restatement of the name. It does not, however, differentiate itself from the nearby get_pool_stats or get_mid_price siblings, so an agent must infer the boundary between them.

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: an agent can infer this is the tool for static pool configuration, but there is no explicit 'use X instead when you need Y' against get_pool_stats, get_order_book, or estimate_fees. The payment-tier paragraph describes how to pay on repeat calls, which is procedural guidance, not tool-selection guidance.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, open-world), and the description layers on genuinely new behavior: a 100 calls/day free tier, 0.002 USDC per call after that, prepaid batches of ~0.01 USDC, and the payment_token/payment_tx handshake driven by the payment-required response. It also flags data may be delayed or wrong.

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 returned metrics, then appends the necessary disclaimers and pricing mechanics. Slightly long on the payment paragraph, but every clause (quota, price, prepay batch, token source) drives agent behavior, so little is wasted.

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 enumerates the returned metrics, which largely substitutes for one, and it fully covers the payment flow and data-quality caveats. Only the precise response shape and pagination/limit behavior are left unspecified.

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 75%, with the schema itself documenting pool format and the two payment parameters. The description adds real meaning by explaining that payment_tx/payment_token are only used after the free tier and that the token holds prepaid calls, plus implying the hours window — enough to compensate for the residual 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+resource ('scorecard-style stats for one pool') and enumerates the exact metrics returned (trade count, taker buy/sell split, VWAP, spread, etc.), which cleanly distinguishes it from siblings like get_ohlcv, get_volume, and get_recent_trades.

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: 'one pool over the last N hours' suggests a per-pool rolling window, and the free-tier/payment paragraph tells the agent how to proceed after quota exhaustion. It never states when to prefer this over get_volume, get_ohlcv, or get_recent_trades, nor any exclusion conditions.

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, and the description goes well beyond them: it discloses rate limits (100 free calls/day then 0.002 USDC/call), the prepaid batch payment flow, the payment-required response and payment_token handshake, and the caveat that data may be delayed or wrong. This is rich operational context an agent needs.

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 purpose and returned fields, then the payment mechanics. Mostly earns its place, though 'Education/information only; not financial advice' is boilerplate that adds little operational value.

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 helpfully enumerates the returned fields and ordering, and fully explains the payment flow that several schema params depend on. An agent has everything needed to call it 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 pool, limit, start_time/end_time, include_tx, and the payment params are already fully documented. The description adds no format or syntax 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?

States a specific verb and resource ('most recent fills in a DeepBook pool'), plus the exact returned fields (time, taker side, price, base/quote size) and ordering (newest first). The 'DeepBook pool' scoping also implicitly distinguishes it from the balance-manager sibling get_bm_fills.

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?

'Optional time range' implies the start_time/end_time use case, but no alternative tool is ever named and there is no when-not-to-use guidance (e.g., use get_ohlcv/volume for aggregates rather than raw fills). Usage is only implied.

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, open-world, idempotent, and non-destructive traits, so the bar is lower. The description still adds real value: free tier of 100 calls/day, then 0.002 USDC per call on Sui mainnet with prepaid batches, the payment-required response flow, and a data-quality caveat ('may be delayed or wrong'). This goes well 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?

It is correctly front-loaded, leading with the returned signal before caveats and pricing. However, two adjacent sentences repeat the same disclaimer ('Information only, not a trading instruction' / 'Education/information only; not financial advice'), and the payment paragraph is long relative to its value. Some pruning is warranted.

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 return-value semantics, and it does: it enumerates the ranges, volatility, regime buckets with numeric thresholds, and the rung count, plus the payment response handling. It is nearly complete, missing only finer response-shape details.

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 pool, payment_tx, and payment_token fully, making 3 the baseline. The description only gestures at payment_token indirectly ('the payment-required response gives an exact amount and a payment_token') and adds no syntax or format detail beyond the schema. Adequate but not additive.

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 derived resource: 1h/4h/24h high-low range, realized volatility, a regime classification with thresholds, and a suggested ladder rung count. This clearly distinguishes it by content from raw-data siblings like get_ohlcv or get_volume. It stops short of naming a sibling alternative, so it lands at 4 rather than 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?

There is no guidance on when to use this versus get_ohlcv, get_volume, or get_mid_price, nor any exclusions. The only contextual rules are the free-tier/payment constraints, which govern cost rather than tool selection. An agent gets no help choosing among the signal-oriented siblings.

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

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

Annotations already establish read-only, idempotent, open-world, non-destructive behavior, and the description still adds substantial context beyond them: a 100 calls/day free limit, 0.002 USDC per call afterward, prepaid batches of ~0.01 USDC, and a payment-required response carrying an exact amount plus payment_token. It also warns data may be delayed or wrong and is not financial advice.

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 core behavior is front-loaded in the first sentence, followed by scoping and payment terms. It is dense but every sentence carries operational information; the payment sentence is long but necessary given the prepaid model.

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 return-value burden, and it does: it enumerates the metrics per pool and the top-pools list. Combined with the payment flow explanation, an agent has everything needed to call it 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%, so the baseline is 3; the description adds the mutual-exclusivity relationship (top only when no pool is given, custom window_hours only for a single pool) and frames payment_tx/payment_token as a post-free-tier workflow tied to the payment-required response, which is more than the schema's field-level text.

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?

Names the exact resource and metrics returned — '24h volume, high/low, last price and % change' — and the alternate branch ('top pools by 24h quote volume if no pool is given'). This is far more specific than siblings like get_pool_stats or get_ohlcv, so an agent can route to it without opening the schema.

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

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

Gives clear branch conditions: pool omitted returns top pools, and window_hours applies only to a single pool. It also explains the payment path when the free tier is exhausted. It stops short of naming an alternative sibling (e.g., get_pool_stats) for when a different metric view is wanted.

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 readOnly/openWorld annotations by disclosing the pricing model (100 free calls/day per client, then 0.002 USDC per call), the prepaid batch mechanism (~0.01 USDC), and the two-step flow where a payment-required response returns the exact amount and a payment_token. It also warns that data 'may be delayed or wrong.' Annotations already cover safety, and this adds rate limits, cost, and a payment handshake the agent must sequence correctly.

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?

Single dense paragraph with the core purpose front-loaded and the operational/payment caveats following. The disclaimers ('education/information only; not financial advice') consume space without helping tool selection, but nothing is redundant enough to be disqualifying.

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 previews the return payload (base/quote assets, tick, lot, min size) and explains the payment-required response shape. Combined with rich annotations, this is nearly complete; only the lack of any pagination or result-volume hint keeps it from a 5.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description adds only marginal meaning (human units, asset filter framing) and largely restates the payment flow the schema already describes. 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 and resource: 'List Sui DeepBook v3 spot pools with base/quote assets and trading params (tick, lot, min size in human units).' An agent knows exactly what comes back. It does not, however, distinguish itself from near-neighbors like get_pool_params or get_pool_stats, so the differentiation half of the 5-bar is unmet.

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 tells the agent the asset filter is optional and that payment params apply only after the free tier, which is genuine usage context. But it never says when to choose this over get_pool_params/get_pool_stats, so the when-not/alternatives bar is not reached.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: that this connector never holds keys or funds and that the user pays from their own wallet, which is useful auth/custody information. It stops short of describing pagination or the return shape.

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

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

The purpose is front-loaded, but the sentence is bloated with legal boilerplate ('Educational templates, not financial advice; no returns promised. All sales final, except where the law requires otherwise.') that consumes space without helping tool selection. Roughly half the text is disclaimer rather than invocation guidance.

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

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

For a zero-parameter, read-only listing tool with no output schema and annotations covering safety, the description is largely sufficient: it names the data source URL and states the fields returned (prices in Sui USDC, versions). It could say more about the response structure, but the essential information for correct invocation is present.

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 the baseline is 4 per the rubric. The description does not need to add parameter meaning, and nothing contradicts the empty schema.

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

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

The description opens with a specific verb+resource ('List ... templates') and enumerates what is included (prices in Sui USDC, versions, buying flow), so an agent can tell this is the catalog-reading tool. It does not explicitly name its siblings (create_template_order, check_template_order), so differentiation is only implied by the 'List' verb.

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 statement of when to use this tool versus create_template_order or check_template_order, and no prerequisites or exclusions. The phrase 'no-checkout agent buying flow' gestures at a downstream purchase path but never tells the agent which sibling to call for it.

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