sdk

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: no assumptions about the liquidation formula, maintenance margin, or what the returned value represents. No contradiction, but no added context either.

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 single line is front-loaded and contains no padding, which is good. However, it is under-specified rather than genuinely concise; the brevity comes at the cost of any useful detail.

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 and 0% schema description coverage, the description would need to explain the inputs and the computed result. It does neither, leaving the agent unable to verify units, formula assumptions, or what the return value means for a 3-parameter calculation 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 0% and all three parameters are required, so the description carries the full burden. It merely restates the parameter names that the schema already exposes, without adding units, valid ranges, or whether 'leverage' is expressed as a multiplier or a fraction. No meaning beyond the schema.

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

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

The phrase 'Liquidation price for a position' identifies the computed resource and the three inputs, so an agent can infer the tool's function. But it is a noun fragment with no verb and no differentiation from the sibling calc_position_size, which is also a calculation tool. Purpose is implied rather than stated.

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 when-to-use guidance, no prerequisites, and no mention of the sibling calc_position_size as an alternative. The agent must guess the context 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 the operation safe, read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds no behavioral context beyond the safety profile—no formula, no assumption about long vs short direction, no handling of invalid entry/stop ordering, and no indication of what the result represents.

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; the computation comes first and the inputs follow. It is appropriately terse, though it is arguably too terse to convey the constraints that the parameters require.

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 calculator with 0% schema coverage and no output schema, the description should clarify the return value's meaning (quantity vs notional, rounding/lot constraints) and the entry/stop ordering requirement. It omits both, leaving real ambiguity about how 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 0%, so the description carries the burden for all four numeric parameters. It restates the parameter names in prose ('account balance, risk percent, entry and stop') but adds no units, formatting, expected ranges, or the critical constraint on relative ordering of entry and stop.

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 computation (risk-based position size) and enumerates the four driving inputs, so an agent knows it's a sizing calculator distinct from a generic math tool. It does not explicitly differentiate itself from the sibling calc_liquidation, but the verb+resource 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?

There is no when-to-use context, no mention of prerequisites (e.g., that entry and stop must be on the same side/ordered correctly), and no comparison to the sibling calc_liquidation. The agent must infer usage entirely from the name and parameter list.

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 openWorldHint, so safety and idempotency are covered without the description. The description adds that these are crypto-moving events and that the data is authoritative over memory, but says nothing about freshness, date range covered, or how 'upcoming' is bounded.

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 value proposition front-loaded and the behavioral instruction second. Nothing 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?

For a parameterless, no-output-schema tool this is nearly complete: purpose, examples, and a usage rule are all present. The only gap is the shape of the response (which events, horizon, event fields like time/importance), which an agent would have to discover at call time.

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?

Zero parameters, so there is no parameter semantics to explain and the baseline applies. The description correctly implies a no-argument call.

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 ('upcoming macro events that move crypto') with concrete examples (FOMC, CPI, NFP), which makes it immediately distinguishable from the price/funding/liquidation siblings. No explicit verb, but 'upcoming events' cleanly conveys the return.

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 when-to-use rule: check this before answering any question about dates, and never answer from memory. Strong actionable guidance, though it names no alternative tool or when-not-to-use condition.

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, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only that the tool reports the current value and classification, which is useful but does not disclose freshness, update cadence, or how the classification is derived.

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 short sentence with no filler and the resource name front-loaded. It reads as a noun phrase without a verb, which is mildly telegraphic but efficient.

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, and it does so at a high level ('current value and classification'). It would be stronger if it specified the 0-100 scale or the classification labels, but it is adequate for a no-argument read 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, so the baseline is 4. There is no argument syntax for the description to clarify and nothing is left ambiguous about the call signature.

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 a specific resource (Crypto Fear and Greed index) and states exactly what is returned: the current value and its classification. It is clearly distinguishable from siblings like get_price or get_funding, though it does not explicitly contrast itself with any of 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 gives no when-to-use context, no mention of what the index is useful for (e.g. sentiment gauging), and names no alternatives. For a zero-parameter single-purpose tool the cost is low, but no guidance is actually present.

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 this a safe, idempotent, read-only, open-world operation, so the safety profile is covered. The description adds only the conceptual definition of funding rates, nothing about freshness ('current' is vague), cross-exchange coverage limits, or rate limiting. With annotations doing the heavy lifting, a 3 is appropriate.

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 efficient sentence with the resource front-loaded and no filler. It is appropriately sized, though it is arguably too thin for the parameter documentation that is missing.

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 lookup with one optional parameter the description covers what the tool returns in broad terms ('current funding rates across exchanges'), but it leaves the symbol parameter entirely undocumented and gives no hint about coverage or update frequency. No output schema exists, so the description carries that burden and only partially discharges 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?

One parameter (symbol) with 0% schema description coverage, and the description never mentions it. It does not say whether symbol is required, what form it takes, or what happens if it is omitted — a real gap given the schema is silent.

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 current funding rates across exchanges') and adds a plain-language gloss of what a funding rate is. It is clearly distinguishable from siblings like get_price or get_open_interest, though it never names an alternative explicitly.

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?

No when-to-use or when-not-to-use guidance, no mention of prerequisites or alternatives among the many get_* siblings. The gloss 'who pays whom to hold a perp position' explains the concept but gives no signal about when an agent should call this instead of get_open_interest or get_price.

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 no behavioral context of its own: no mention of candle count/limits, pagination, history depth, or whether interval falls back to a default. It essentially restates the annotation-covered basics.

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, with the resource stated first and the usage hint second. Nothing is padded, though the second sentence is thin enough that more substance could have fit at no cost to brevity.

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 the return shape (OHLC fields, volume presence, ordering, how many candles) and it does not. Combined with the unexplained symbol format, an agent cannot confidently invoke this without guessing.

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 only 50% (symbol is undocumented) and the description adds no parameter meaning at all — it does not state the expected symbol format (e.g. 'BTCUSDT') or explain the interval units beyond what the schema already lists. With half the parameters undocumented in both places, the description fails to compensate.

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 gives a specific verb+resource: 'OHLC candles for a symbol.' It is distinguishable from siblings like get_price or get_funding, though it does not explicitly contrast itself with them. Purpose is clear but sibling differentiation is left 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?

'Use this to compute indicators or check a setup before trading' gives a use context but names no alternatives (get_price, get_markets) or when-not-to-use conditions. The guidance is implied rather than explicit 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the data is real (not simulated) and is aggregated across eight exchanges, which hints at source breadth. It stops there, saying nothing about update cadence, pagination, or how 'recent' relates to the 24h window in the title.

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 or repetition. Size is proportional to a one-parameter read-only 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?

There is no output schema, so the description carries some burden for explaining what comes back — the fields, units (USD notional?), and ordering of liquidation events are unstated. The time window is also inconsistent: the title says 24h but the description only says 'recent.' For a simple market-data tool this is workable but leaves real gaps.

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 single parameter 'symbol' has 0% schema description coverage, so the schema contributes nothing and the description must compensate — it does not mention symbol at all. An agent cannot tell from either source whether symbol is a filter, a required market identifier, or what format it takes, nor what the default (unfiltered) behavior is when it is omitted.

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 and scope: 'recent real liquidation events aggregated from eight exchanges.' The verb is implicit in the noun phrase (this returns events), but the term 'real' usefully signals these are actual market events rather than the computed results of the sibling calc_liquidation. It is clear enough to select the tool, though it never explicitly contrasts itself with calc_liquidation.

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, no conditions or exclusions, and no named alternative. An agent must infer from the word 'real' that this is for actual liquidation data and calc_liquidation is for hypotheticals. That inference is left entirely to the reader.

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 non-destructive, so the safety profile is covered; the description adds the returned fields and workflow placement. It says nothing about pagination, result size, or how the optional filter affects the 'every symbol' claim, so it adds only moderate 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 short sentences: the return content is front-loaded and the call-timing guidance follows immediately. No filler text at all.

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 needed work by enumerating the key returned fields and the call timing. The only real gap is the asset_class filter, which an agent using this tool would likely want explained.

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 single asset_class enum parameter has 0% schema description coverage and is never mentioned in the description. Worse, 'Every tradable symbol' arguably implies results are unfiltered, which sits awkwardly with the optional filter, so the description neither explains nor compensates for 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 the resource precisely ('every tradable symbol') and names the returned attributes (asset class, max leverage, taker fee), which lets an agent tell it apart from price/screener siblings. The verb is only implicit, but the scope 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?

'Call this before sizing a trade' gives a clear contextual trigger tied to a downstream workflow. It does not name alternatives such as get_screener or get_price, nor say when this is not needed, so it falls short of the 5 tier.

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 fully covered elsewhere. The description adds only a conceptual gloss ('how much leveraged money is committed'), with no information on units, time granularity, snapshot vs. historical behavior, pagination, or auth/rate limits.

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 short sentence that leads with the resource name and resource scope. The trailing clause 'how much leveraged money is committed' is explanatory rather than essential, but the whole description is compact and front-loaded.

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 would need to convey the return shape, units, and whether the value is a single snapshot or history - none of which it does. For a market-data tool with an undocumented parameter and no output contract, this is too thin.

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% and the single 'symbol' parameter is undocumented in the schema, so the description carries the burden. 'Per symbol' hints that symbol scopes the result, but gives no format example (e.g. BTCUSDT), no case conventions, and does not clarify that symbol is in fact optional given zero required 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?

States a specific verb+resource combination ('Open interest per symbol') and adds a plain-language gloss of what the metric means. It is clear what the tool returns, but it draws no distinction from adjacent siblings like get_funding, get_liquidations, or calc_liquidation, leaving the agent to infer the boundary itself.

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 when-to-use guidance, no exclusions, and no mention of alternative tools for related derivatives metrics. The only implied usage is 'you want open interest data', which the agent could already guess from the name.

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 behavioral context by disclosing that no API key is required, which is an auth precondition the annotations do not 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?

Two short sentences, zero waste, with the core purpose front-loaded and the access note trailing. Nothing is padded or repeated from the 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?

For a one-parameter read tool with rich annotations and no output schema, the description covers purpose, scope, and access needs. A brief note on the response shape (e.g. units or timestamp of the 24h change) would make it fully self-sufficient.

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 single parameter and its suffix convention are fully documented in the schema. The description adds no symbol syntax or format detail 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?

The description states a specific verb and resource ('Live price and 24h change') and enumerates the asset classes covered (crypto perp, stock, index, forex, metal), which is enough to distinguish it from siblings like get_klines or get_funding. It stops short of naming an alternative tool explicitly, so it lands just below the top band.

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 resource ('live price'), and 'No API key needed' removes an access precondition, but the description never says when to pick this over get_klines, get_markets, or get_screener, nor does it state exclusions. Adequate but with a clear gap.

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 the useful detail that this is an aggregated technical output, but says nothing about scope of 'top' perps, count, or freshness of 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?

A single front-loaded sentence with no filler; the scope qualifier ('top USDT perps') precedes the list of returned fields. It is efficient, though very terse 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 input params and no output schema, the description carries return-value burden and does name the key fields (score, RSI, MACD, funding, OI). What remains unclear — how many setups, what 'top' means, refresh cadence — are minor gaps for a zero-argument read-only screener.

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 — baseline 4 applies. No misleading claims about inputs are made.

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 (scored trade setups across top USDT perps) and enumerates the composite signals returned (0-100 score, RSI, MACD, funding, OI), so an agent can tell this is a screening/ranking tool rather than a raw data fetch. It stops short of naming or contrasting any sibling (e.g., get_markets, get_funding), which is why it isn't 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?

There is no sentence about when to reach for this screener versus the individual indicators it aggregates (get_funding, get_open_interest, get_klines). No preconditions, no exclusions, no alternative routing — usage is left entirely to inference from the name.

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 this a safe, idempotent, non-destructive read, so the bar is lower. The description adds genuinely non-structured context: an authentication requirement ('Requires an API key') and the semantic model of books versus keys. It still says nothing about pagination or the shape of 'lifetime numbers'.

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 with no filler, and the resource being listed is front-loaded. The final sentence about API keys is a slightly abrupt add-on, but each sentence carries 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 zero-parameter, read-only listing tool with no output schema, the description conveys the domain model (books, keys, journals, balances, reports) and the auth prerequisite. It could go further on what the returned records contain, but nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; the baseline is 4. The description correctly implies the call is scoped entirely to the authenticated account rather than requiring any selector.

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 (every book/sub-account of this account) and what it returns (lifetime numbers and the keys bound to it), then defines what a book is. It is clear, but it never distinguishes itself from adjacent paper_* siblings like paper_balance or paper_report, so an agent must infer the boundary.

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: the mention that 'a key minted with a book name trades that book' hints this is the discovery call for book-scoped workflows, and the API-key prerequisite is stated. There is no explicit when-to-use, when-not, or named alternative among the many paper_* 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed world, so the safety profile is covered. The description adds a genuine piece of context beyond that: the API-key authentication requirement, plus the exact read fields returned.

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 fragments with zero filler; the returned fields are front-loaded and the prerequisite is appended last. Nothing could be removed without losing 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 no-argument read-only snapshot with no output schema, enumerating the return fields compensates well for the missing schema, and the auth requirement is stated. The only real gap is failing to disambiguate from the near-identical paper_equity sibling.

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 clarify and the baseline of 4 applies. Schema coverage is reported at 100% with an empty object 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 precise resource (your paper account) and enumerates exactly what it returns: balance, equity, free margin, unrealized P&L. It does not, however, distinguish itself from the sibling paper_equity, which an agent could easily confuse it with.

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

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

There is no when-to-use guidance and no mention of alternatives, despite several overlapping siblings (paper_equity, paper_accounts, paper_positions). The only guidance is the prerequisite 'Requires an API key', which tells the agent how to authenticate but not when to choose this tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, covering the safety profile. The description adds two useful facts beyond structured data: the order must be 'resting' (unfilled) and an API key is required. It still omits failure behavior 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?

Two short sentences with the action front-loaded and no wasted words. Brevity is appropriate for a one-parameter tool, though the second sentence is a precondition rather than usage 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 simple mutation tool with annotations covering safety and idempotency, the description is minimally adequate: it names the action, the API key requirement, and the resting-order constraint. It lacks any return/failure semantics and gives no help locating the order_id, leaving an agent partially equipped.

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 0% and the single parameter order_id is undocumented in the schema; the description offers no help on its format or where to obtain it (e.g., from paper_orders). With one non-trivial parameter, the description should compensate but does not.

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 (cancel a resting limit order) and narrows scope with the qualifier 'resting', which distinguishes it from position-closing siblings like paper_close. It does not name or distinguish itself from paper_modify_order or paper_close explicitly, so differentiation is only partial.

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 only guidance is a precondition ('Requires an API key'), which is not a when-to-use rule. There is no indication of when to cancel versus modify (paper_modify_order) or close (paper_close), nor what happens if the order has already filled.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description adds two useful facts beyond the annotations: closing can be partial, and an API key is required. It does not explain what happens on repeat calls or against an already-closed position, so it stays at a modest level.

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, front-loaded sentences with no filler; the core action comes first and the prerequisite second. It is efficient, though the auth note is near-boilerplate across this tool family.

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 destructive mutation with no output schema, the definition omits important operational context: where the id comes from (presumably paper_positions), what a partial close does to realized P&L, and error behavior. Annotations cover the safety hint, but an agent still lacks enough to call this confidently in edge cases.

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 only 50%: the required 'id' parameter carries no description anywhere, and the description never clarifies whether it refers to a position id, order id, or account id. The 'fully or partially' phrase loosely maps to 'pct', but the schema already documents that parameter's 1-100 range, so the description adds no compensating meaning for the undocumented half.

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 ('Close a simulated position') and adds the full/partial scope, which is the key distinction from a plain close. It does not explicitly name sibling tools (e.g. paper_open, paper_modify_order), but the action is unambiguous on its own.

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 prerequisite 'Requires an API key' is stated, which is real guidance. However, there is no when-to-use vs alternative framing — an agent gets no help distinguishing closing a position from paper_modify_order, paper_cancel_order, or paper_sltp on the same account.

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 the safety profile is covered. The description adds genuine context beyond that: the exact return composition (bucketed realized P&L plus a live unrealized endpoint and max drawdown) and the API-key requirement.

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 delivers the resource first and the return contents second, with no filler. The compound colon-list is dense but every clause carries 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 read-only tool with no output schema, the description compensates by spelling out what the curve contains. Parameters are handled by the schema and the auth prerequisite is stated, leaving little an agent needs that is missing.

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

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

Schema description coverage is 100%, with both days (1-90, default 30) and step_min (5-1440) fully documented, so the baseline is 3. The phrase 'per bucket' loosely ties to step_min but adds no syntax or default information beyond the schema.

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

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

The description states a specific resource and enumerates its composition (starting balance, realized P&L per bucket, live unrealized point, max drawdown), so an agent knows exactly what comes back. It doesn't explicitly contrast itself with siblings like paper_balance or paper_report, which are the nearest neighbors.

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: 'equity curve ... per bucket' suggests a time-series view as opposed to a point-in-time snapshot from paper_balance. The one explicit guideline, 'Requires an API key,' is a prerequisite rather than a when-to-use rule, and no alternative or exclusion is named.

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 the safety profile (idempotentHint=true, destructiveHint=false, readOnlyHint=false). The description adds meaningful context beyond that: it requires an API key, and passing set mutates the default, while omission performs a read. It stops short of describing the response payload, but no output schema exists to cover that.

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 venue list are front-loaded, followed by the read/write mechanic and auth requirement. It is a single dense paragraph with mild redundancy between the prose and the schema param description, but no wasted 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?

For a one-parameter, no-output-schema tool, the description covers everything needed: what it shows, the enumerated venues, the read/write behavior of set, and the API key requirement. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the single 'set' parameter is already fully documented ('Omit to read. A venue key from the list, or "marginpad" to reset.'). The description largely repeats this (venue key or "marginpad" for default/reset), adding 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?

The description states a specific verb+resource: it lists modeled venues with taker rates and referral discounts, and shows/changes the current default fee schedule. This is clearly distinguishable from siblings like paper_accounts or paper_realism, and an agent can tell exactly what the tool returns and mutates.

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 explains the read-vs-write condition: 'Pass set to change the default' versus omitting it to read. That is clear operational guidance, though it names no sibling alternatives or when-not-to-use 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 declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description still adds real context beyond them: 'Simulated money only' and 'Requires an API key' tell the agent about the sandbox and auth requirement. It does not, however, explain non-idempotency (duplicate-order risk) or margin/leverage exposure.

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 and tightly written, with the core behavior in the first sentence and routing/safety notes after. Every sentence carries information, though the misleading 'type' sentences spend space on a non-existent parameter.

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 8-parameter mutation tool with no output schema and 25% schema coverage, the description covers purpose, alternative, simulation scope, and auth, which is a fair amount. It falls short by not explaining the optional sl/tp/leverage/client_order_id parameters and by introducing a 'type' concept with no schema backing, leaving the agent to guess how limit vs stop is actually selected.

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 only 25% (8 params, just margin_usd and limit_price documented), so the description is expected to compensate and largely does not. Worse, it repeatedly references a 'type' parameter ('type "limit"' / 'type "stop"') that does not exist in the input schema, which could mislead an agent into passing a phantom argument. It does clarify limit_price semantics ('fills AT that price') but leaves sl, tp, leverage, and client_order_id unaddressed.

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 ('Place') and resource ('a resting order that fills only when the market reaches your price, and fills AT that price'), and immediately scopes it against the sibling paper_open. The limit-vs-stop entry semantics let an agent distinguish it from the other paper_* order tools.

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

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

Explicitly routes the agent: 'To open right now use paper_open instead,' naming the alternative and the condition that selects it. It also explains when each order type applies (pullback entry vs breakout entry), so both the when-to-use and the alternative are 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 non-readonly, non-destructive, idempotent semantics. The description adds the API-key/auth requirement and the 'in place' mutation model, which is useful. It does not say what happens to fields left unspecified or what the call returns, but with annotations covering safety this is acceptable.

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, no filler, with the core action and mutable fields front-loaded ahead of the auth caveat. Every phrase 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 mutation tool with no output schema, the description covers the action, mutable fields, and auth. It omits behavior for unchanged/unspecified fields and does not note that it only applies to resting (open) orders in the paper account context.

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 0%, so the description carries the burden and does it well: it maps price/stop-loss/take-profit/margin/leverage/trailing stop to limit_price, sl, tp, margin_usd, leverage, and trail_pct. order_id is only implied, but the field-to-parameter correspondence is largely recoverable.

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: modify a 'resting limit or stop order in place', and enumerates the mutable fields. This distinguishes it from paper_limit_order (place) and paper_cancel_order (cancel), though those siblings are not named explicitly.

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 'change a resting order in place' implies when to use it, but no alternatives are named (e.g., cancel-and-replace vs in-place edit) and there are no preconditions beyond the auth note. Usage is only implied, not 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 confirm a mutating, non-idempotent, non-destructive write, so the safety profile is partly covered. The description still adds real value beyond them: the simulated-funds guarantee ('no real funds are ever at risk') and the API-key auth requirement. It omits failure behavior and the idempotency affordance offered by client_order_id.

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 with zero waste; the core action is front-loaded and the two follow-ups (fund safety, auth) are distinct, useful facts 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?

For a nine-parameter mutation tool with no output schema, the description should say what is returned (position, fill price, order id) and how the idempotency and dry-run paths behave. Those gaps leave an agent underinformed despite the solid safety and auth statements.

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?

Nine parameters with only 56% schema description coverage, and the description explains none of them. Nothing is said about sl/tp semantics, trailing stops, leverage caps, or how dry_run interacts with the write. The heavy parameters are left entirely to the schema.

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

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

The description states a specific verb and resource ('Open a simulated position') plus an execution detail ('at the live price') that implicitly separates it from the limit-order sibling paper_limit_order. It does not explicitly name that sibling or any other alternative, so the differentiation is inferable rather than stated.

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: 'at the live price' signals market-style execution versus paper_limit_order, and the API key requirement is stated. There is no explicit when-to-use guidance, no note on prerequisites such as sufficient paper balance, and no routing rule to the limit or SL/TP 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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the auth requirement ("Requires an API key") and the bounded return window (last 20 terminal 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?

Two short, front-loaded sentences with no filler. The primary content (what is returned) comes first and the auth caveat second.

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 and no parameters, the description carries the burden of describing returns, which it does reasonably well (resting orders plus last 20 terminal orders) along with the auth requirement. It could note the 20-item truncation implications or ordering, but is essentially complete for a zero-arg read 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 and the schema is an empty object with full coverage, so there is nothing to document. Baseline 4 applies since no parameter semantics are needed.

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 gives a clear verb+resource: it returns the caller's resting limit orders plus the last 20 filled/expired/cancelled ones. It is specific about scope and contents, though it does not explicitly contrast itself with close siblings like paper_trades or paper_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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternatives among the many paper_* siblings. The agent can infer it is a read/list tool, but nothing states which sibling to prefer for viewing trade history or positions.

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 genuinely useful context beyond that: the returned values are live (mark-price derived) and P&L is net of fees, plus the authentication prerequisite ("Requires an API key").

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 tightly packed sentence with the resource and data content front-loaded. Nothing is wasted, though the auth caveat and the status clause are compressed into the same line rather than separated.

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, safe read tool with a fully documented single parameter and no output schema, the description covers what is returned (positions with live mark price and net-of-fees P&L), how to filter, and the auth requirement. Only sibling differentiation 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% and the single enum parameter is self-documenting ("Omit for both"). The description clarifies that status="open" narrows to open positions only, which adds a little meaning over the schema, but it does not explain the closed case. 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 the resource (paper positions) and even the payload contents (live mark price and P&L net of fees), which is more specific than a bare noun. It does not explicitly distinguish itself from close siblings like paper_orders or paper_trades, so an agent must infer the boundary from the noun alone.

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?

No when-to-use guidance and no named alternatives among the many paper_* siblings. The only routing hint is the filter behavior of status, which is a parameter concern rather than usage 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 annotations (idempotent, non-destructive), the description discloses the concrete defaults that apply when nothing is passed (live-price fills, no slippage, flat 0.5% maintenance margin), warns that the default diverges further from reality as position size grows, states the API-key requirement, and notes that open positions retain the margin they were filled with.

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 purpose and defaults, then the write path, then the read path — logical order. The parenthetical venue-rate list is long but each value is decision-relevant; nothing else is 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 still tells the agent what a read returns (current setting, all venue rates, the full size-tier ladder) and covers the auth requirement, defaults, and persistence semantics, so nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by adding information the schema lacks: the venue maintenance-margin rates behind each margin_venue value and the default slippage/ margin behavior that the booleans toggle away from.

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 exactly what the tool governs — the realism of paper-trade fills and maintenance margin — and documents both modes (omit fields to read, pass fields to configure). Its scope is unique among siblings like paper_fees and paper_sltp, so there is no ambiguity about which tool an agent should 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?

It gives clear operative guidance: pass slippage and/or margin_tiers to turn realism on, pass margin_venue to adopt a named venue's rate, or omit every field to read. It never states when realism should *not* be enabled (e.g. when reproducing a default backtest), but the use context is otherwise unambiguous.

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, disclosing that this is a stateful mode-switch that reroutes sibling tools to a separate replay journal, that stops/targets/liquidations are evaluated per candle, what stop does ('closes everything at the cursor'), and that an API key is required. Annotations only say it's a non-readOnly, non-destructive, idempotent write.

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 purpose, then modes in a logical order. Slightly dense and colon/semicolon-heavy with nested parentheticals, but every clause (speed meaning, cursor fields, stop behavior) carries real 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 stateful, no-output-schema tool this is nearly complete: it describes what status returns (cursor, price, progress, candles up to the cursor), what stop returns (summary), and the side effects on sibling tools. The only gap is that field-level detail of the returned journal/status objects is left implicit.

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 per-parameter docs already exist; the description adds relational semantics the schema lacks, clarifying that symbol and day must be supplied TOGETHER to trigger a start and that speed is market-seconds-per-real-second. It does not need to restate the enum, so 4 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?

Names a specific verb+resource ('replay one past UTC day on MarginPad's 1-minute candles') and states the core value prop ('backtest with the real routes'), which immediately distinguishes it from pure-query siblings like get_klines or paper_sim.

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 maps each invocation shape to a mode: symbol+day STARTS, no arguments reads status, act='stop' ends it. It also names the downstream siblings (paper_open/paper_positions/paper_close) and states the condition under which they switch to the replay journal - nothing is left to inference.

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

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

Annotations already establish readOnly, idempotent and non-destructive behavior, and the description adds genuinely new context beyond them: an API key is required, and part of the payload is entitlement-gated by plan tier. It stops short of describing pagination or how the written findings are produced.

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 resource and window front-loaded, followed by what is returned and the access requirements. Nothing is wasted, though the mid-sentence tier split makes it slightly harder to scan than a two-clause structure would.

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 it reasonably well by enumerating totals, skill score, win rate and per-dimension breakdowns plus written findings. Auth and entitlement constraints are covered; only return format details are absent.

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

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

Only one parameter, and the schema already documents it fully ('1-30, default 30') for 100% coverage. The description's '30-day' framing matches the default but never mentions that the window is configurable, so it adds no meaning beyond the schema.

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

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

States a specific verb+resource: a 30-day trading report for 'this account' derived from its own closed trades, plus the exact metric set returned. That cleanly separates it from list-style siblings like paper_trades or paper_equity, though it never names an alternative explicitly.

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 implies when it is useful (you want aggregated performance analytics for the paper account) and discloses tier gating: totals and skill score are free, the deeper breakdowns and written findings need API Pro or above. It does not tell the agent when to prefer this over paper_equity or paper_trades, so 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?

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false) by disclosing exactly what happens: closed trades are archived rather than deleted, resting orders are cancelled, and the report/equity curve restart. It also states the open-position refusal and the auth requirement, which the annotations do not 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?

Three compact sentences, front-loaded with the outcome, then side effects, then the guard condition and auth note. Every sentence adds information with 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?

For a zero-parameter, no-output-schema mutation tool, the description covers post-conditions, preconditions, and authorization. Nothing an agent needs before invoking it 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?

The tool takes zero parameters, so the schema needs no elaboration and the baseline is 4. The description correctly provides no parameter details rather than inventing them.

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

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

States a precise verb (restart/reset) on a specific resource (this key's paper book) and names the exact resulting state ($10,000). An agent can immediately tell it apart from siblings like paper_accounts, paper_replay or paper_close.

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 a clear precondition and refusal condition: 'Refused while positions are open - close them first,' which implicitly routes to paper_close, plus the API-key requirement. No explicit alternative tool is named for other reset-like needs, but the usage context is unambiguous.

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 it is a non-read-only, non-destructive, idempotent operation. The description adds substantial behavior beyond that: out-of-range values are refused and never clamped, positions keep the simulation they were filled under, presets start from defaults as a clean slate, reading returns every field with range/default/effect, and an API key is required.

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

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

The prose is long but front-loaded with the default posture before the field inventory, and each sentence carries a distinct concept (defaults, configurable surface, presets, read behavior, refusal policy, persistence, auth). For a 20-parameter engine, the length is defensible, though a couple of clauses 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 compensates fully: it explains what a read returns, what presets exist, that invalid values are refused rather than clamped, that existing positions retain their simulation, and that auth is needed. An agent has everything required to call this correctly.

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

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

Schema coverage is 100%, so the 20 parameters are already documented individually; baseline would be 3. The description adds value by grouping the fields by concern (book size, crossing cost, latency, fill behavior, refusals, fees/funding, liquidation), explaining preset semantics, and clarifying the read mode that the schema only hints at.

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: it configures the whole paper-trading simulation engine, and enumerates the exact knobs (margin, slippage, latency, partial fills, reject rate, fees, funding, liquidation). It is clearly the setter for simulation state, but it never names siblings such as paper_realism or paper_reset, so the sibling differentiation is left 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?

It gives clear context: pass a preset for the easiest route, omit every field to READ, and requires an API key. It also states a default posture (deliberately easy, good for learning, optimistic for proving a bot), which helps an agent decide when this is appropriate. It stops short of explicitly naming the alternative read tool or the reset tool.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description need not restate them. It adds that the target must be an open simulated position and that an API key is required, but says nothing about what happens to unspecified sl/tp values or invalid price ranges.

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 with the action and target front-loaded and the prerequisite trailing; 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 mutation tool with no output schema and only partial parameter documentation, the definition is serviceable but thin: it omits the distinction from paper_modify_order and gives no detail on partial updates or failure modes.

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 25% (only trail_pct is documented), so the description carries extra burden. It names the three concepts (stop-loss, take-profit, trailing stop) that map to sl, tp and trail_pct, but leaves the required id and the null semantics of sl/tp unexplained.

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 (move) plus the resources it acts on (stop-loss, take-profit, trailing stop) and scopes them to an open simulated position. It does not, however, distinguish itself from the closely named sibling paper_modify_order, which an agent could easily confuse it with.

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

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

The only guidance is a prerequisite ("Requires an API key"); there is no statement of when to reach for this tool versus paper_modify_order or paper_close, nor any exclusion about what kind of position qualifies beyond "open simulated".

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=true, idempotent=true, non-destructive, so the safety profile is covered. The description adds two things the annotations do not: it is paginated, and it requires an API key — a genuine auth prerequisite. It still does not state page-size limits or ordering semantics.

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 compact clauses with the resource and its paging trait front-loaded, followed by the auth requirement. Every clause carries information, though 'for measuring a strategy' is slightly soft framing rather than operational detail.

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 low-complexity, zero-required-parameter read tool with full annotation coverage, the description supplies the essentials: what the ledger contains, that it pages, and that auth is needed. With no output schema present, the exact record fields are left unspecified, which is the main remaining 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 coverage is 50%: 'before' is documented as an epoch-ms cursor from next_before, but 'limit' is bare (only a default of 100). The description's mention of 'paging' frames both parameters but adds no format, bounds, or default behavior beyond the schema. Baseline 3 is appropriate at this coverage level.

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 — a closed-trade ledger — with paging, and adds the framing that it is the complete record for strategy measurement. This distinguishes it from open-order siblings like paper_orders and paper_positions, though it never names those alternatives explicitly.

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 'the full record for measuring a strategy' implies the use case (post-hoc performance analysis of closed trades), but there is no explicit when-to-use, when-not-to-use, or routing to siblings such as paper_orders or paper_report. Usage is inferable rather than directed.

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