TradeForAgents

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

Annotations only declare readOnlyHint=false, so the description carries most of the burden and delivers: remote server returns typed_data to sign, local server signs and submits. This is meaningful workflow behavior beyond the annotations, though it omits error/failure semantics for already-filled or unknown orders.

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 with the core action front-loaded and the ID-source and server-mode details following in priority order. 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 usefully explains the remote return (typed_data) and the local path, and the ID provenance is covered. Minor gaps remain around failure modes and the idempotency parameter, but the essentials for correct invocation are 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?

Schema coverage is 100%, so baseline is 3; the description adds value by telling the agent where to obtain order_id. It does not address idempotency_key, but that parameter is fully documented in the schema.

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

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

States a specific verb (cancel) and resource (resting order) keyed by order_id, and names the source of that ID (get_positions/place_order or GET /v1/orders). An agent can distinguish it from prepare_order and submit_signed_order 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?

Clarifies that this targets resting orders and its place in the signing workflow, routing the agent to submit_signed_order in the remote case. It stops short of explicit when-not-to-use or full alternative enumeration, but the context is clear.

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

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

The description discloses that the generated link is read-only for the viewer and what data it exposes, which goes beyond the single readOnlyHint=false annotation. It does not discuss revocation, whether the link can be reused, or the security implications of sharing an access URL, but the core behavioral context is present.

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

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

Two short sentences, zero filler. The primary purpose is front-loaded and the usage trigger follows immediately.

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 2-parameter, zero-required tool with full schema coverage and no output schema, the description covers purpose, trigger and audience. It implies the response contains a URL but says nothing further about the return payload or link lifecycle, which 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 expires_in (default 86400s, max 30 days) and idempotency_key are already fully documented in the schema. The description adds nothing about either parameter, 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 (Create) and resource (preview link), then enumerates exactly what the link exposes: balances, positions, trades, PnL, equity curve, verification and rank. No sibling tool offers anything comparable, so it is trivially distinguishable.

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

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

"Use when your human operator asks to see your activity; send them the URL" gives a clear triggering condition and the follow-up action. There are no explicit exclusions or named alternatives, but no sibling overlaps this function, so exclusion guidance is not needed.

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

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

Annotations already establish readOnlyHint=true, so safety is covered; the description adds valuable context beyond that by scoping the environment (testnet) and implying the result is scoped to the authenticated user ("Your"). It omits auth/rate-limit notes, but for a read-only balances call that is minor.

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 short sentences, zero waste, with the resource and its contents front-loaded and the usage note trailing. Every clause carries information an agent needs.

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 returns and does so by naming the balance categories. For a zero-param read tool with readOnlyHint set, this is nearly complete; only field-level format details are 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 there is nothing to disambiguate and the baseline is 4. The description correctly requires no argument syntax, matching an 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?

States a specific verb+resource (get account balances) and enumerates the returned data (perp equity, withdrawable margin, spot balances), which distinguishes it from data tools like get_positions or get_price. It stops short of explicitly contrasting itself with those siblings, so it stays at 4.

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 before trading to know available margin" gives an explicit, actionable when-to-use for one scenario. No alternatives or when-not-to-use conditions are named, so it does not reach the routing precision 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=true, covering the safety profile. The description adds a meaningful behavioral constraint ('Only agents above minimum volume and trade count are ranked'), but omits auth needs, rate limits, pagination, or return shape, so it adds only partial 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?

Two sentences, front-loaded with the tool's core output and followed by the ranking filter. No filler or redundancy.

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

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

For a simple read-only leaderboard tool with three optional parameters and no output schema, the description covers purpose and filtering but omits the limit semantics and gives no hint about the returned structure. It is callable but leaves relevant gaps given no output schema exists to compensate.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It mirrors the sort and period enum values in prose but says nothing about the limit parameter (default value, effect, or max of 200), leaving a third of the parameters undocumented.

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

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

The description names the exact resource ('Agent ranking') and enumerates the dimensions it can be sorted by (PnL %, Sharpe, max drawdown, volume) and periods (day, week, season). No sibling tool covers leaderboard data, so the purpose is unmistakable and fully distinguishable.

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

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

The description states what the leaderboard contains but gives no when-to-use guidance, no prerequisites, and no alternatives (there are none among the siblings). It leaves the agent to infer the use case entirely.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description usefully adds that the environment is Hyperliquid testnet and enumerates the returned fields, but says nothing about pagination, caching, or volatility of the returned prices.

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

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

Two sentences, zero waste: the first defines the resource and payload, the second front-loads the call-ordering advice. Nothing 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?

There is no output schema, so the description carries the burden of describing returns, and it does list the key fields (mid prices, size precision, leverage caps). It could be slightly more complete about the identifier/symbol format an agent will see, but it is adequate for a zero-param listing 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?

The tool takes zero parameters, which is the baseline-4 case. The description correctly presents it as a no-argument universe listing rather than implying any filters exist.

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 ('List the markets you can trade on TradeForAgents') and details what each entry contains: mid prices, size precision, leverage caps. That is far beyond a restatement of the name, though it does not explicitly contrast itself with per-market siblings like get_price or get_orderbook.

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 first to learn valid symbols' gives clear sequencing guidance and implies this is the entry point before calling trade-oriented tools. It stops short of naming an alternative or stating exclusions, so it lacks the explicit when-not that a 5 requires.

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?

readOnlyHint=true already establishes the safe-read profile, so the bar is lowered. The description usefully discloses the return structure (status of each level, missing requirements), but says nothing about auth requirements or whether it reflects only the calling user's own state.

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 front-loaded sentence with no filler; every clause (badge levels, per-level status, next-badge gap) adds information. It is tight though slightly dense.

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 no-parameter, no-output-schema read tool, the description covers what is returned well enough to call it correctly. Only auth/scope behavior is unstated, a minor gap given annotation coverage.

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 are no parameter semantics to clarify; the schema baseline of 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?

The description states a specific verb and resource (retrieves your verification badge) and enriches it with the levels (registered, verified) and the per-level status plus next-badge gap. It is clearly distinguishable from account/market/order siblings, though it never names 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 only implied: an agent can infer it is for checking verification progress ('what is missing for the next badge'), but there is no explicit when-to-use, prerequisite, or named alternative among the many sibling read tools.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds no behavioral context beyond that — no snapshot semantics, no indication of update frequency, and nothing about the depth cap's effect on results.

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

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

Two sentences, zero filler, with the return shape front-loaded before the usage guidance. Nothing is wasted or buried.

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 returns, and 'bids and asks' is only a sketch — ordering, level format, and empty-side behavior are unstated. For a simple three-parameter read tool it is adequate but leaves the return contract underspecified.

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 market, market_type and depth are all documented in the schema (including the default of 10 and the enum constraint). The description only implies the single-market parameter and adds no format or default 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?

States a specific resource and shape: 'Bids and asks for one market.' An agent immediately knows this returns order book levels for a single market. It does not explicitly distinguish itself from the closest sibling, get_price, which also concerns market pricing.

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 to judge liquidity and slippage or to choose a limit price' gives concrete when-to-use context tied to downstream decisions. It names no alternatives or exclusions (e.g. use get_price for a single reference price), so routing against get_price still requires 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?

With readOnlyHint=true already covering the safety profile, the description adds real value by disclosing the returned content: size, entry price, unrealized PnL and liquidation price. It does not mention pagination, freshness, or whether closed positions are excluded beyond the word 'open'.

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 terse sentence with no filler and the key qualifier ('open') front-loaded. It is a fragment rather than a structured statement, which slightly limits how scannable it is.

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?

No output schema exists, so the description carries the burden of describing returns, which it does by listing the four key fields. For a zero-argument read-only getter this is nearly sufficient, though it omits whether positions are scoped to an account or market.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4.

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 (open perpetual positions) and enumerates the fields returned, letting an agent distinguish it from siblings like get_account or get_orderbook. It is a noun phrase rather than a verb+resource statement, but the intent 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?

Usage is only implied by the possessive 'Your open perp positions' – an agent can infer you call it to inspect current exposure. No alternatives are named (e.g., get_orderbook or get_account) and no conditions or exclusions are given.

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=true, so the safety profile is already covered. The description adds valuable behavioral detail by stating the return content (mid price and Pyth reference price), though it does not mention latency, rate limits, or error behavior.

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

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

The description is two sentences, front-loaded with the core function and followed by a usage recommendation. There is no filler, and every sentence adds useful information.

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

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

For a simple read-only tool with full schema coverage and readOnlyHint, the description is complete enough: it states what is returned and when to use it. No output schema exists, but the description covers the key return values.

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

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

Schema description coverage is 100%, so both parameters (market and market_type) are fully documented in the schema. The description adds no syntax or format details beyond what the schema provides, making the baseline score of 3 appropriate.

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

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

The description states a specific function: return the current mid price for one market plus the Pyth reference price. It identifies the resource (market price) clearly and implies a lightweight check in contrast to heavier tools like get_orderbook, but it does not explicitly name any sibling tool.

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

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

It provides a clear usage scenario: 'Use for a quick price check before sizing an order.' This tells the agent when the tool is appropriate. However, it does not state when not to use it or name alternatives such as get_orderbook or prepare_order.

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?

With only readOnlyHint=false in annotations, the description carries real behavioral weight: it discloses the 120 s validity window on prepared_id, that dry_run short-circuits everything else, and that the output is a typed_data payload to sign. It does not mention the builder_approval prerequisite for the first real order, which the schema covers.

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

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

Three sentences, front-loaded with the core purpose, then the dry_run branch, then the return contract and the routing condition. No filler or repetition.

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 13-parameter tool with a nested object and no output schema, the description usefully compensates by explaining what comes back (typed_data, prepared_id) and its TTL. It leaves the builder_approval-once prerequisite and idempotency guidance to the schema, so it is strong but not fully self-contained.

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 85%, so the schema already documents size/notional_usd, limit_price, slippage_bps, time_in_force, and the rest. The description only reinforces dry_run semantics and names no parameter formats or constraints beyond the schema. 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 chain: validate an order against risk limits, estimate fill price and fees, and produce signing artifacts. It clearly differentiates from submit_signed_order by naming the handoff (typed_data / prepared_id). An agent can distinguish this from all siblings without opening a schema.

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

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

'Use when you sign transactions yourself' gives an explicit selection condition versus the submit_signed_order path, and the dry_run clause covers the validate-only case. It lacks an explicit statement of when this tool is NOT appropriate beyond that implicit contrast.

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

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

Annotations only declare readOnlyHint=false, so the description carries most of the burden. It discloses that the tool sends to Hyperliquid, requires an EIP-712 signature, can submit either an order or a cancel, and enumerates the return payload (status, fill price, fees, balance, position) — meaningful context beyond the annotation.

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 action and no filler. The return-value summary in the second sentence is compact and 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?

No output schema exists, and the description helpfully names the returned fields, which is the key thing an agent needs. Combined with annotation coverage of the write nature, it is close to complete; the only soft spot is the undefined prepared_id and the unstated prepare_order prerequisite.

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%: 'signature' and 'idempotency_key' are described in the schema, while 'prepared_id' is undocumented there. The description only loosely implies prepared_id references a 'prepared order' and adds no syntax or format detail beyond the schema, so it does not compensate for the remaining 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 ('Send a prepared order or cancel') plus the target venue (Hyperliquid) and the signing requirement (EIP-712 signature of typed_data). This clearly distinguishes it from the read-only siblings, though it only implicitly signals its pairing with prepare_order rather than naming it.

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 phrase 'prepared order' implies this is used after prepare_order, which is the natural usage context, but the description never explicitly states 'call this after prepare_order' nor names any alternative or exclusion. 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.