flox-mcp

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

With no annotations, the description carries the burden and it does disclose real behavioral facts: results are 'exact to the wei' (precision), the tool needs the optional `lrvx` dependency (a hard prerequisite), and it is a single-pool quote rather than a router. It doesn't say what happens when `lrvx` is absent or how errors surface, so not a 5.

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

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

Four short sentences, front-loaded with what the tool returns and followed by the usage rationale, size format, and dependency. Every sentence carries information; nothing is padded.

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

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

There is no output schema and no annotations, yet the description names the return contents (average price and price impact per size), the input size format, and the dependency requirement. Missing only edge behavior (missing `lrvx`, invalid sizes), which keeps it at 4.

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% and the two parameters are documented in the schema; the description only restates the size format ('NUMBER SYMBOL' strings) and says 'one AMM pool'. It adds little about the nested pool spec's venue params beyond what the schema already declares, 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 output ('depth / slippage table for one AMM pool') with the fields returned (realized average price, price impact) and the scope (one pool, list of sizes). An agent can tell it produces a per-size quote table rather than executing a swap. It does not explicitly name the sibling it contrasts with (price_amm_swap / route_amm_swap), which keeps it short of a 5.

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

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

'Use this to reason about how large a trade a pool can absorb before quoting' gives a concrete scenario and implies the pre-trade sizing use case, which distinguishes it from swap-execution siblings. No explicit when-not or named alternative, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden. It discloses the dry_run default (important for safety), and mentions account gating rules. However, it does not state what happens in live mode, whether the operation is reversible, or what the response format is. For a mutation tool, this is a moderate gap, but the dry_run default is a significant behavioral disclosure.

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 that are dense with purposeful information: the core action, the filter, the critical default, and the context/usage. Every phrase earns its place, and the most important detail (dry_run default) is mentioned early.

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 3-parameter tool with no output schema, the description covers the essential context: purpose, filter, default behavior, and account gating. It does not mention return values or error semantics, but given the tool's simplicity and the presence of situational context (panic stop), it is reasonably complete. A more detailed description could note expected outcome, but this is adequate.

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% (dry_run is not described in the schema). The description adds value by specifying the dry_run default and explaining the account scope rules more clearly than the schema. It also clarifies that symbol=0 means 'all symbols'. These details go beyond the schema's basic descriptions, partially compensating for the undocumented dry_run parameter.

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

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

The description clearly states the action ('Cancel every open order') and the optional filter ('optionally filtered by symbol'), with a specific verb and resource. It also differentiates from the sibling cancel_order by implying batch scope and positions itself relative to set_kill_switch, making its role unambiguous.

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

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

The description provides clear context on when to use this tool ('panic stop' after set_kill_switch) and explains the account gating variation from place_order. It does not explicitly contrast with cancel_order, but the phrase 'cancel every open order' makes the broad-vs-single distinction clear. The guidance is solid but could be more explicit about not using it for single-order cancellation.

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?

No annotations, so the description carries the full burden. It discloses 'Default dry_run=true' and 'Talks HTTP to the local ControlServer', which adds useful behavioral context. But it never explicitly states that when dry_run=false the order is actually cancelled, nor does it mention side effects or return behavior – a significant gap for a mutation tool.

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

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

Four concise sentences, each adding value. The purpose is front-loaded, followed by implementation, default, use case, and a constraint. While not as tight as a two-sentence example, there is no fluff and it reads efficiently.

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 3-parameter mutation tool with no annotations and no output schema, it covers the essential purpose, default behavior, and account constraints. However, it does not clarify what happens when dry_run=false (presumably real cancellation) or the result/error behavior, leaving an agent uncertain about the tool's actual effect.

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 33% (only account is described). The description compensates by clarifying order_id as the target ('by id'), dry_run default behavior, and account gating rules. This adds meaningful semantics beyond the bare schema, though it does not fully describe each parameter's acceptable values or interactions.

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 'Cancel one open order by id' – a specific verb, resource, and scope. It clearly differentiates from siblings like cancel_all by emphasizing a single order and the 'open' status.

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

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

Provides context: 'Useful for operator-driven cleanup or panic stop' and explains account gating similar to place_order. However, it does not explicitly mention alternatives like cancel_all for bulk cancellation, so it lacks explicit when-not guidance.

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

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

With no annotations, the description carries the burden and does so partially: it discloses the 1 MiB input cap and the optional `lrvx` dependency requirement. It does not cover error behavior, failure modes when the dependency is missing, or the return shape, so it is good but not complete.

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 action, followed by the use case and the two constraints. The middle sentence is slightly long but every clause (pre-strategy check, non-obvious parameters) 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 and no annotations, so the description should describe what comes back, but it only says 'return the output' without clarifying shape (array of floats, scalar, alignment with input length). Input constraints and dependency are covered, leaving a meaningful gap for a compute 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 coverage is 100%, so both parameters (data, name) are already documented in the schema with formats and casing rules. The description adds no direct parameter detail beyond referencing window/period/smoothing behavior, 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?

Specific verb+resource: 'Run a single lrvx indicator over a list of floats and return the output.' It is clearly distinguishable from siblings like list_indicators (enumerate) and get_indicator_values (retrieve values from recorded/strategy context) because it computes ad-hoc on a caller-supplied array.

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 states when to use: sanity-check an indicator on a small price array BEFORE wiring into a strategy, especially for window/period/smoothing parameters. It gives clear context but does not name a specific alternative tool or state when-not-to-use, so it stops short of a 5.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses query matching behavior (AND by default, FTS5 operators pass through) and an important boundary that the index is allowlist-only and private tracker/strategy/author files are NEVER indexed. It does not mention auth needs, rate limits, or result ordering beyond top-k, which are minor for a read-only search.

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?

Purpose and usage guidance are front-loaded, followed by a well-delimited query-syntax section and a bulleted set of canonical queries. It is on the long side, but each block (syntax rules, allowlist note, workflow routing) adds distinct value rather than restating the schema.

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

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

For a two-parameter, no-output-schema search tool, the description covers purpose, invocation triggers, syntax, and index scope thoroughly. The only meaningful omission is the shape/nature of returned results, which an agent would benefit from since no output schema exists.

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, but the description goes beyond the schema by documenting FTS5 operators (OR, NEAR, *, parens) and the exact-match quoting behavior for the query parameter. The k parameter is left entirely to the schema, so it does not lift this to a 5.

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

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

States a specific verb and resource ('Top-k full-text search over the lrvx documentation') and enumerates the covered content types (guides, reference, tutorials, error codes, bindings, explanations). The purpose is unmistakable, but it never explicitly differentiates itself from overlapping siblings such as lookup_error_code, lrvx_venue_guide, or get_example, leaving that routing to inference.

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

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

Gives concrete usage triggers — 'call it whenever the user asks how do I X / what does Y do / where is Z documented' — plus a set of canonical workflow queries that map user intents to specific searches. It is strong on when-to-use but offers no guidance on when NOT to use it in favor of the specialized lookup 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?

With no annotations, the description carries the burden of disclosing behavior. It clearly states that it walks the causal-parent chain to the root and returns the chain in order. It omits edge cases (e.g., missing root, cycles) and performance characteristics, but for a read-only traversal tool the core behavior is well explained.

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 action and result, followed by practical usage examples. Every sentence adds value with no 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?

Given no output schema, the description adequately describes the return value ('chain in order from requested event to its root') and gives a concrete walk-through example. It does not detail the shape of each chain element, which would improve completeness, but it is sufficient for a straightforward traversal 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 schema covers 'max_depth' with a description and default, but 'event_id' has no schema-level description. The description adds conceptual meaning ('the requested event', causal-parent chain) but does not specify the format or expected identifier style for event_id. Schema coverage is 50%, and the description only partially compensates.

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

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

The description clearly identifies a specific verb ('Walk an event's causal-parent chain back toward the root') and resource ('event's causal-parent chain'), and explains the output ordering. It does not explicitly contrast with the sibling tool 'explain_event', leaving some ambiguity about when to choose one over the other.

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 provides concrete use cases ('why did this fill happen', 'trace the cause of order 42') and explains what the chain reveals. However, it offers no explicit when-not-to-use guidance or alternatives, so it stops short of a full 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?

With no annotations, the description carries the behavioral burden and largely does: it discloses the return shape (field name, type, units, human description) and the resolution rule that a raw dict is matched against known struct shapes. It doesn't explicitly declare the operation read-only or idempotent, but the introspection nature is unambiguous.

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

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

Two sentences, front-loaded with the core purpose, then inputs, then the usage trigger. No filler and no 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?

No output schema exists, yet the description fully specifies the return payload, and with zero required parameters there are no invocation prerequisites an agent is missing. Complete for a read-only introspection tool.

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

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

Schema description coverage is 100%, and the schema already states the enum values and the 'if type_name is omitted' fallback, so the description mostly restates what is in the schema. It adds only the slight framing that the two inputs are alternatives, which earns a baseline 3 rather than more.

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 (Describe) plus the exact resource (fields of a lrvx event struct), and scopes it with the concrete struct names and accepted inputs. An agent can distinguish it from explain_decision, get_event_log, or docs_search without opening any schema.

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

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

Provides a clear trigger condition ('Use when the user asks "what's in this event"') and explains both accepted input modes. It stops short of naming an alternative tool to redirect to when the question is about behavior rather than fields, so there is context but no exclusions.

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

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

With no annotations, the description carries the behavioral burden and largely delivers: it discloses the dry_run default, the paper/live account gating rule inherited from place_order, and that mismatched-account rows are skipped. It stops short of explaining what dry_run=true versus false returns or the side effects of a live flatten, so it is not a 5.

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

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

The description is compact and front-loaded: purpose first, then default behavior, then when-to-use and constraints. Every sentence carries information, with no repetition of schema details.

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 flatten action it covers the core invocation concerns: what it does, when to use it, required-account constraints, filtering, and dry-run default. It lacks output/error behavior, but there is no output schema and the tool is simple enough that this 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?

The schema already documents symbol and account, and the description adds meaning beyond it: dry_run defaults to true, account is required with the same gating as place_order, and mismatched rows are skipped. The uncovered dry_run parameter therefore gets useful context.

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

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

The opening sentence is specific: 'Close every open position with opposite-side market orders, optionally filtered by symbol' names the verb, the resource (positions), and the mechanism. It is clear enough that an agent will not confuse it with pure order-cancellation tools, though it does not explicitly name a sibling alternative.

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

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

It explicitly states when to use the tool: 'Use for ‘close everything’ operator actions or end-of-day flatten.' It does not list alternatives or when-not-to-use cases, but the ‘close everything’ framing provides a clear selection signal.

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?

States read-only nature and mentions filters AND-compose and default limit 100. No annotations provided, so description carries the burden; it covers key behavioral traits but lacks details on pagination or response format.

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 concise sentences with examples, front-loaded with purpose. No unnecessary words.

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?

Covers main use cases and parameter behavior, but without output schema, it does not explain return values. Time range parameter format is not clarified.

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 40%; description adds context like 'Filters AND-compose' and 'Default limit 100', but does not elaborate on strategy, from_ts_ns, or to_ts_ns beyond being filters.

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 specifies the verb 'query' and the resource 'engine event log', listing event types (signals, orders, fills, risk checks). It clearly distinguishes from sibling tools like get_open_orders or get_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?

Provides explicit use cases ('what happened in the last 5 minutes', 'show me all the signals from ema-trend') but does not explicitly state when not to use or mention alternative 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the provenance and reliability guarantee of the output (bundled, CI-validated, canonical), which is real value beyond the schema, but it says nothing about auth requirements, error behavior on an invalid topic, or result size/format.

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 action and resource, then the usage trigger, then the enumerations. Dense but every sentence does work; the em-dash rationale is slightly long but earns its place by justifying the 'before writing from memory' rule.

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 2-parameter lookup with no output schema, the description covers purpose, trigger, and valid values adequately. The main gap is that it doesn't describe the shape of the returned code block or how multiple examples are returned, though that is a minor omission for this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates the topic and language enumerations already present in the schema; its only added meaning is mapping user-intent phrases to topics, which is marginal.

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 (Return) and resource (canonical lrvx example code) with the scoping dimensions (topic, language) named inline. It clearly separates itself from 'generated code from memory,' but does not explicitly distinguish itself from sibling doc/code tools like docs_search or scaffold_strategy, so an agent must infer which to pick.

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 states the trigger ('when the user asks show me how to {backtest|connect to ccxt|wire an indicator}') and the competing alternative it should preempt ('BEFORE writing fresh code from memory'), with a rationale (CI-validated vs. unvalidated). The when-to-use and the alternative are both spelled out rather than 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?

Explicitly states the tool is read-only, a key behavioral trait. No annotations provided, so the description carries the burden; it does so well by clarifying the live nature of the data.

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

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

Two sentences, no wasted words. First sentence states the core function, second gives usage examples. Perfectly concise.

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 tool with two parameters and no output schema, the description covers purpose, filtering, read-only nature, and use cases. Does not mention error handling for invalid strategies, but that's acceptable for this simplicity.

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 schema has 50% description coverage; only 'name' has a description. The description adds context for 'name' ('filter to one indicator'), which matches the schema. The 'strategy' parameter is not elaborated, but the description doesn't need to repeat the schema; it adds some value.

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

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

The description clearly states the tool returns live values of indicators in a strategy, with an optional name filter. It distinguishes from siblings like 'compute_indicator' and 'list_indicators'.

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

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

Provides concrete examples like 'what's the EMA reading' and 'is the RSI overbought now', guiding the agent on when to use it. Doesn't explicitly mention alternatives, but the examples are sufficient.

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

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

With no annotations, the description fully discloses the return shape {active, reason, since_ns}, the idle fallback when no snapshot exists, and the read-only nature. This goes beyond the minimum and clearly explains runtime 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?

Three concise sentences, each adding distinct value: action and output, usage scenarios, and edge case plus sibling alternative. No redundant wording.

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 tool with one optional parameter, the description covers purpose, return values, fallback behavior, and relationship to the sibling tool. The return shape is stated inline, so no output schema is needed.

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 state_path parameter is already fully documented. The description adds minor context by implying state_path is an override to the runtime snapshot, but this is not substantial enough to exceed the baseline.

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

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

The description clearly states the tool reads kill-switch state from the runtime state snapshot with a specific verb and resource. It distinguishes from the sibling set_kill_switch by explicitly noting 'to flip the switch use set_kill_switch'.

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?

Explicit usage scenarios are given: 'is trading halted' and 'why was the kill switch tripped'. It also provides guidance on when not to use it (use set_kill_switch instead) and explains the no-snapshot edge case.

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 no annotations, the description carries the full burden. It discloses that the tool is read-only and describes the special response when the engine is not running. This is good behavioral context, though it could be more thorough about normal return behavior or potential errors.

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 three sentences long, each adding value: purpose, usage guidance, and a behavioral note. It is front-loaded and free of unnecessary words.

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?

The description covers the purpose, usage, and a specific edge case (engine not running), but fails to describe the normal return structure. Since no output schema is present, the description should explain what the successful response contains (e.g., list of orders, fields). This gap lowers completeness.

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 input schema already provides 100% coverage with clear descriptions for both parameters. The description merely rephrases the filter parameter without adding new meaning, so it meets the baseline but does not enhance understanding 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 clearly states 'Read in-flight orders from the runtime state snapshot,' providing a specific verb and resource. It also gives usage examples like 'what orders are pending,' which solidifies the purpose and distinguishes it from mutation tools like cancel_order or place_order.

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 explicitly states when to use the tool: 'Use this for what orders are pending / do I have anything sitting on Bybit.' It does not explicitly list when not to use or alternatives, but the context is clear given the sibling tool names and the read-only nature.

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?

Despite no annotations, the description thoroughly discloses read-only nature, the output structure (realized + unrealized + fees per strategy), and an error behavior (engine_not_running idle response when no snapshot). This fully compensates for missing annotations.

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

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

Three sentences covering purpose, usage, and behavior. No fluff, every sentence serves a purpose. Front-loaded with the core action in the first sentence.

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?

Covers return values and error case. No output schema, but description compensates by listing realized/unrealized/fees. Doesn't mention output format or limits, but for a simple snapshot read, it's adequate.

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 clarifying that filtering by strategy only affects the breakdown, not the total ('total still reflects the full snapshot'). This nuance is not 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?

The description clearly states 'Read PnL totals plus per-strategy breakdown' and gives concrete query examples ('what's my PnL', 'how is strategy X doing today'). It distinctly identifies the resource (runtime snapshot) and the action (read). Among 30+ sibling tools, none overlap in purpose, making it easily 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?

Explicitly advises when to use: 'for what's my PnL / how is strategy X doing today'. It doesn't list alternatives or when NOT to use, but the context is strong enough for correct selection. Lacks explicit sibling differentiation, but the use case is narrow enough.

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?

No annotations are supplied, so the description carries the full burden and does so: it declares the tool is read-only ('never modifies state'), explains snapshot resolution via LRVX_RUNTIME_STATE or state_path, documents the {snapshot_age_ms, data:[...]} return shape, and — most valuably — specifies the {'engine': 'not_running'} fallback is a normal pre-engine state not to be surfaced as an error.

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 usage triggers, then return shape, then path resolution, then the notable edge case. Every sentence carries information an agent needs; there is no filler or repetition of the tool name.

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 annotations and no output schema, the description must supply safety, return shape, and failure semantics — and it covers all three, including the pre-engine not_running case that would otherwise be mishandled. An agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so all three parameters are already documented, and a 3 is the correct baseline. The description restates the state_path resolution order (env var then passed path) but adds no syntax, format, or matching semantics for account/strategy beyond the schema's 'Filter to one account/strategy'.

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 ('Read positions from a running lrvx engine') plus the mechanism (runtime state snapshot). Sample user utterances and the returned field list let an agent distinguish it from get_open_orders, get_pnl, and flatten_positions without opening any schema.

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

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

Gives explicit trigger phrasing ('what's in my positions', 'show me the BTC position', 'is strategy X long or short') which is strong positive guidance. It does not, however, name competing siblings such as get_open_orders or get_pnl or state when not to use this tool, so the routing is implied rather than exclusive.

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 no annotations, the description carries the burden of behavioral disclosure. It states 'Read-only' (implying no side effects) and describes the output format. This is adequate transparency for a simple state retrieval tool. No contradictions with annotations (none provided).

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-loading the action and output. Every part adds value: the verb, the output type, contents, read-only nature, and example prompts. No wasted words.

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 one parameter and no output schema, the description sufficiently covers purpose, parameter (via example), and return structure (JSON dict with listed fields). No further context is needed given the simplicity and sibling tool landscape.

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 input schema has 0% description coverage (no parameter descriptions in schema), so the description must compensate. It implies the single 'name' parameter is the strategy identifier via the example 'ema-trend'. While not explicitly stating the parameter's meaning, the example and context make it sufficiently clear. Baseline for zero-param schema coverage is 4, and this meets that.

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

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

The description clearly states the tool returns a strategy's current state as a JSON dict, specifying included fields (params, position view, last decisions). It also provides concrete usage examples ('what does strategy X think right now'), which distinguish it from sibling tools that handle orders, indicators, etc.

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 indicates read-only usage and provides user query examples, implying when to call the tool. However, it does not explicitly exclude cases where other tools (e.g., get_positions) might be preferred, nor does it mention prerequisites like the strategy must exist. The guidance is good but lacks explicit boundaries.

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 no annotations, the description carries the full burden and does disclose meaningful behavior: it is a wrapper where the CLI stays the source of truth, what each template bundles (including a dry-run safety harness for `live`), and that the result contains CLI output plus a Next steps section. It omits failure/overwrite behavior on the filesystem and any prerequisite that the lrvx CLI must be installed.

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

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

Front-loaded with the core action and the wrapper caveat, then usage triggers, then template enumeration. The template list is long but each item carries decision-relevant detail; the trailing 'Next steps / docs_search' note is marginal but not wasteful.

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 and no annotations, so the description must stand alone — and it largely does, covering purpose, triggers, template choices, and expected return content. Remaining gaps (CLI prerequisite, target_dir collision behavior, error modes) are moderate rather than fatal for a 3-param scaffolding 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 coverage is 100%, so the baseline is 3; the description earns extra by explaining what each enum value actually scaffolds (research = notebook + sample data + main.py, live = CCXT broker + dry-run harness, indicator-library = standalone package with tests), which the bare enum cannot convey. It adds little for project_name/target_dir 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 ('Create a new lrvx project from a bundled template') and clarifies its role as a thin MCP wrapper over the canonical `lrvx new` CLI. It is clearly distinct in kind from siblings like scaffold_strategy or docs_search, though it never names a sibling to contrast against.

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

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

Gives concrete trigger phrases ('set up a new lrvx project', 'I want to scaffold a research notebook', 'start a live trading bot'), which is strong use-when guidance. It stops short of stating when NOT to use it or pointing at alternatives (e.g. scaffold_strategy for strategies vs. this for whole projects).

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?

No annotations are supplied, so the description carries the full burden. It discloses that filtering is case-insensitive, but says nothing about ordering, pagination behavior, or result size beyond the schema's limit default, and does not state the read-only nature explicitly. Adequate for a low-risk enumeration tool but not rich.

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

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

Two tight sentences, purpose front-loaded, with the filter case-sensitivity note as a useful trailing qualifier. No filler, though the quoted example phrasing is slightly verbose relative to the rest.

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 list tool with no output schema, the description covers what is enumerated, when to reach for it, and filter semantics. It lacks any note on output shape or result ordering, but nothing critical to invoking 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 baseline is 3. The description does add one genuine fact beyond the schema — that the substring filter is case-insensitive — but omits the 'cpp' surface that appears in the schema's language list, creating a slight mismatch with the documented enum values.

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

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

States a specific verb ('Enumerate') and resource ('public exports of one lrvx binding surface') and enumerates the concrete surfaces covered (C-API/Python/Node/Codon/QuickJS), which lets an agent separate it from siblings like list_capi_functions (single-surface C-API) at a glance.

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

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

Gives explicit trigger conditions: user asks 'what does the {Python|Node|Codon} binding expose?' or wants to browse a binding before picking a symbol. It does not name an alternative tool or state when NOT to use this one (e.g., vs list_capi_functions), so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses the data source ('committed ABI snapshot', implying static, version-pinned results rather than live state) and enumerates the returned fields. It omits pagination/limit-default behavior, but the core behavioral profile is clear.

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 zero padding; purpose and return shape are front-loaded ahead of the usage trigger. Every sentence 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?

With no output schema, the description appropriately specifies the returned fields (name, return type, parameter types). For a two-param, no-required-arg tool this is nearly complete; a note on the limit default or result size would close the 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 description coverage is 100%, so limit and filter are fully documented in the schema itself. The description adds no meaning beyond that (e.g. it doesn't explain match semantics of the filter), so the baseline of 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 (search) and resource (the lrvx C-API surface / exported lrvx_* functions) and clarifies the return shape. It is clearly distinguishable from sibling list tools such as list_bindings, list_indicators, and list_strategies.

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 explicit trigger conditions: when the user is writing FFI code (Codon, QuickJS, Rust cgo, ctypes) or asks 'what C symbols can I call'. This is strong when-to-use guidance, though it names no exclusions or alternative tool for adjacent questions.

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?

No annotations are provided, so the description carries the full burden. It discloses the shape of what is returned (class signature, batch function, single-input scalar vs OHLC tuple vs multi-output), which is the key behavioral trait for a discovery/listing tool, though it does not explicitly state read-only semantics or any auth constraints.

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

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

Two sentences, zero filler. The capability statement comes first and the usage trigger second, so the agent gets purpose before 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, zero-required-parameter discovery tool with no output schema, the description explains both the invocation trigger and the structure of the returned data, which is exactly the gap an absent output schema would otherwise leave.

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% and the single 'filter' parameter is fully documented in the schema. The description never mentions filtering at all, so it adds no meaning 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 (List) and resource (every indicator exposed by the lrvx Python binding) and enumerates the returned attributes (class signature, batch function, shape). It is clearly distinguishable from siblings like compute_indicator, get_indicator_values, and suggest_indicator.

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

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

Gives explicit trigger conditions: when the user asks 'what indicators does lrvx support' or before suggesting an indicator name. This implicitly routes away from suggest_indicator/compute_indicator, but it never explicitly states when NOT to use it or names an alternative 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?

No annotations are provided, so the description carries the full burden, and it does declare 'Read-only' plus the scope it enumerates (only what the running engine knows). It omits edge behavior such as what is returned if the engine is not running, which keeps it short of a 5.

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

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

Two sentences, no filler: the first defines the resource and return payload, the second gives the safety profile and the invocation triggers. Everything is front-loaded and every clause 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 zero-param, read-only list tool with no output schema, the description supplies the key missing pieces: the safe read-only nature and the fields returned. It is essentially complete, with only minor edge-case behavior (no running engine, empty results) 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The description correctly implies no filtering inputs are available.

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 (List), a concrete resource (strategies known to the running lrvx engine), and the returned fields (name, status, subscribed symbols). This clearly separates it from the single-strategy sibling get_strategy_state, though it never names that sibling 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?

It gives explicit trigger phrasing: use when the user asks 'what's running' / 'which strategies are active'. That is strong positive routing guidance, but there is no when-not condition or named alternative (e.g. use get_strategy_state for detail on one strategy).

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?

No annotations are provided, so the description carries the burden. It usefully discloses the return payload (fix recipe, common causes, diagnostics) and implies a side-effect-free lookup, but never explicitly states this is a read-only, non-mutating operation, and says nothing about failure behavior for unknown or malformed codes.

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 tightly written sentences with the purpose and example front-loaded, followed by the usage directive. 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?

With no output schema, the description correctly compensates by enumerating what the returned documentation page contains, and the single required parameter is fully covered by the schema. Only minor gaps remain (behavior on unknown codes, read-only confirmation).

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 with 100% schema description coverage, so the schema already documents the field and its case-sensitivity. The description's inline example 'E_SYM_001' duplicates the schema example and adds no new semantics beyond it.

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

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

States a specific verb (Resolve) and resource (lrvx error code) plus the output form (full Markdown documentation page with fix recipe, common causes, diagnostics). This is clearly distinguishable from siblings like docs_search or explain_event, which serve different lookup intents.

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

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

Gives explicit triggering context — 'Use whenever a LrvxError is raised in user code' — plus a strong negative directive ('never guess at a fix from the message alone'). It does not name an alternative sibling (e.g. docs_search) for non-error-code documentation needs, so it falls just short of full routing 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?

With no annotations, the description carries full burden and does well: it discloses return contents (local name, kind, signature), the cross-language resolution behavior, and a conditional '## Gotchas' section. It omits failure behavior (what happens when a symbol is not found) and any auth/prerequisites, which keeps it from a 5.

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

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

Purpose and cross-language scope are front-loaded, and each sentence mostly earns its place. It is slightly verbose toward the end (the 'never guess' admonition and gotchas explanation partly restate intent), but no sentence is wasted enough to drop below 4.

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 must explain return values—and it does: local name, kind, signature per binding, plus the Owner.method convention and the conditional Gotchas block. For a two-parameter resolver, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so both parameters are already fully documented, establishing the baseline of 3. The description reinforces the any-spelling acceptance and the language filter but adds little syntax or format detail beyond what the schema already provides.

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 (resolve) and resource (lrvx symbol) with explicit scope: across every surface (C++, C-API, Python, Node, Codon, QuickJS). It also clarifies that methods resolve as Owner.method, which distinguishes it from sibling listing tools like list_bindings and list_capi_functions.

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?

Explicit when-to-use: 'Use this whenever the user names a struct, function, or indicator and you need to know what it's called in *their* language.' It further routes behavior (never guess at cross-language spelling) and names the alternative mechanism (the `language` arg to filter to one binding).

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 no annotations, the description carries the full behavioral burden. It discloses that the tool takes no arguments, returns bundled text, is cheap, and produces a Markdown narrative, which strongly implies a safe read-only operation. It could be slightly more explicit about side effects or permissions, but the practical behavior is clear.

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 front-loaded with the key instruction to call it first, then explains the return value and cost profile. Every sentence is useful, and there is no redundant or filler content.

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 overview/discovery tool with no output schema, the description provides enough context: what it returns, how it is organized, and why it is useful for a fresh session. Nothing essential for correct invocation 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 has zero parameters and 100% schema description coverage, so the baseline is 4. The description reinforces this with 'No arguments,' matching the empty schema without adding unnecessary parameter detail.

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

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

The description clearly states the tool returns a Markdown narrative of the lrvx toolkit, organized by category, with canonical workflows and recent additions. It distinguishes itself from the many operational siblings by being the orientation/overview tool rather than a specific action 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 explicitly says to call it FIRST when you don't know which lrvx MCP tool to use, giving a precise trigger condition. It also clarifies no arguments are needed, so there is no ambiguity about when and how to invoke it.

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

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

With no annotations, the description carries the burden and does well: it discloses that it takes no arguments, is cheap, is pure bundled text (implying no network/side effects), and returns Markdown. It never explicitly states read-only/absence of mutation, but the 'pure bundled text' framing strongly implies it.

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?

Efficiently structured: usage condition first, return contents second, invocability/cost third, exclusion last. The opening sentence is dense with comma-separated scenario lists, but every clause earns its place by narrowing the trigger.

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 must describe the return value -- and it does so thoroughly (guide contents enumerated). For a zero-argument documentation tool, nothing an agent needs is missing.

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

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

Zero parameters, so per the rubric the baseline is 4. The description reinforces this with 'No arguments,' leaving no ambiguity about invocation.

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 (the optional lrvx::venue module guide) and enumerates exactly what it covers: headers, order vocabulary, derivatives waterfall, multi-agent demo, build flag, verification posture. It also explicitly distinguishes itself from run_backtest, so an agent can route correctly without opening sibling schemas.

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

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

Front-loads a concrete use trigger ("Use when the user wants to BUILD A MARKET rather than trade on one") with three example scenarios, and closes with an explicit exclusion plus the named alternative ("NOT for an ordinary single-strategy backtest over historical data -- use run_backtest"). Both when and when-not are covered.

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 zero annotations the description carries the full burden, and it delivers: it discloses the transport (HTTP to the local ControlServer), the credential source (LRVX_CONTROL_URL / LRVX_CONTROL_TOKEN), the default-simulate behavior of dry_run=true, and the out-of-band approve_token requirement for live dispatch. This is exactly the non-obvious behavioral context an agent needs for a mutation tool.

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

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

Purpose is front-loaded, followed by transport/auth behavior, safety default, and usage scope in four dense sentences with no filler. Every sentence carries distinct 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 9-parameter mutation tool with no annotations and no output schema, it covers purpose, auth, safety, and approval prerequisites thoroughly. Return shape and failure/error behavior are not described, which keeps it from a 5.

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

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

Schema coverage is 67% and the schema already documents dry_run, approve_token, account, type, price, and reason. The description reinforces the dry_run/approve_token semantics but adds no scope, format, or constraint detail beyond what the schema states (qty, side, symbol remain undocumented in both). Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Place an order through the user's running lrvx engine') and scopes it well beyond a tautology. The closing line ('manual hedges or operator-driven order entry') separates it from sibling order/swap tools like route_amm_swap and price_amm_swap.

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 usage context ('manual hedges or operator-driven order entry') and surfaces the dry_run default plus the live-tier approve_token prerequisite. It does not name an explicit alternative or a when-not condition, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden and does reasonably well: it discloses exactness to the wei, integer-curve arithmetic, lossless 256-bit handling via decimal strings, and the optional `lrvx` dependency requirement. It stops short of stating the operation is a pure read with no state mutation or describing failure modes.

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 usage, then the input-format and dependency caveats. Every sentence carries distinct information with no 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 pure computation with no annotations and no output schema, the description covers what it does, supported venues, input encoding, and the dependency. It could say more about the returned quantities (output amount, price impact), which is a modest gap given the absence of an output schema.

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

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

Schema description coverage is 100%, so the schema already documents venue, pool, i, j, and amount_in. The description reinforces the amount format (native wei/lamports as decimal strings) but adds little beyond what the schema and its enum/nested-object definitions already convey. Baseline 3 is appropriate.

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

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

The description names a specific verb (Price) and resource (a DEX swap against an AMM pool) and enumerates the three supported AMM types, so the agent knows exactly what it computes. It does not, however, differentiate itself from siblings like amm_price_impact or route_amm_swap, which it arguably overlaps with by claiming to 'measure price impact'.

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 usage context ('quote a fill or measure price impact') and ties it to specific pool types, which is better than nothing. But with a sibling literally named amm_price_impact, the overlap is left unresolved and no when-not-to-use or alternative routing is stated.

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 no annotations, the description carries the disclosure burden and does well: it reveals that it shells out to a CLI (`lrvx tape record`) or a script (`backfill_to_tape.py` using ccxt), and that the output is a `.lrvx` directory consumable by `BacktestRunner.run_tape`. It omits operational caveats such as network/API-key requirements and that live mode is open-ended until interrupted, keeping it from a 5.

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

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

Three front-loaded sentences, each carrying distinct information: what it does, how it does it, and when to reach for it. Dense but 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 9-param tool with no annotations and no output schema, the description supplies the missing behavioral and result context (mechanism, output artifact, downstream use). It is complete enough to invoke correctly, though it does not cover failure modes or live-mode termination.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including mode, data_type, and the date-range fields. The description's mode=live/historical breakdown largely restates schema content, 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+resource ("Capture market data into a `.lrvx` tape") and goes further by naming the two implementation paths keyed to `mode`. An agent understands both the outcome and the mechanism, and no sibling in the list records data (replay_pool_tape/replay_window only replay).

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

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

Gives explicit trigger phrasing ('record some BTC data' / 'pull a month of klines for backtest' / 'tape the last hour of trades') that maps user intent to the tool. It does not name alternatives or exclusions, but the recording domain is unambiguous relative to 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?

With no annotations, the description carries the burden and does reasonably well: it discloses the returned series (price/reserves/LP-value/impermanent-loss/drift), the fact that replay is deterministic against the exact curve, and an important operational constraint (requires the optional `lrvx` dependency). It stops short of stating side-effect/purity guarantees or any cost/size 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?

Three sentences, front-loaded with the action and followed by outputs, use case, and dependency. Dense and mostly waste-free, though the returned-series enumeration and the dependency note could be tightened slightly.

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

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

No output schema exists, and the description compensates by naming the series the tool returns, plus the required dependency. For a compute-only backtest over nested pool/swap objects, an agent has enough to invoke it correctly; only error/edge behavior is 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?

Schema description coverage is 100%, so the schema already documents `pool`, `swaps`, and `evm_logs` in detail. The description restates the swaps-vs-evm_logs choice ("a list of swaps (or decoded Uniswap v2 Swap logs)") without adding syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: backtest/replay a DEX position from a recorded pool history through the exact curve. That is clearly distinct from generic siblings like run_backtest or replay_window, but the description never names those siblings or draws the boundary 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?

"Use this to evaluate an LP position or a trading sequence against a real transcript" gives a use case, but there is no when-not guidance and no comparison to the closely related replay_window, whatif, or run_backtest tools. Usage is implied rather than routed.

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 no annotations, the description carries the full burden. It discloses that the tool is read-only with sandbox-only mutations, which is a key behavioral trait. However, it does not explain auth needs, rate limits, or implications of parameter values.

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

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

The description is three sentences, to the point, front-loaded with the main action, and provides necessary context without 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?

Given 4 parameters (including nested objects) and no output schema, the description lacks enough detail about parameters, return values, and inner workings. The usage examples help but do not cover the full complexity.

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% (one parameter described). The description does not explicitly describe parameters; it only hints at time window and strategy via context. This insufficiently compensates for the low schema coverage.

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

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

The description clearly states the tool runs a sandbox replay over a time window, with a specific verb ('run') and resource ('sandbox replay'). It distinguishes from sibling tools like run_backtest by emphasizing sandbox-only and read-only nature, but does not explicitly name alternatives.

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

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

Provides usage examples like 'replay the last hour' and 'rerun this period in sandbox', giving clear context. However, it does not mention when not to use this tool or suggest alternatives among 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?

With no annotations, the description carries the full burden and largely meets it: it documents the return shape, the human 'NUMBER SYMBOL' amount format, symbol-based direction resolution, that a mis-routed swap raises rather than returning a quiet zero, and that the optional `lrvx` dependency is required. It stops short of clarifying whether the swap is actually executed or only quoted.

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

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

Front-loads the core purpose, then layers returns, the amount convention, and the dependency requirement in dense sentences with no filler or repetition. Every sentence carries usable 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?

There is no output schema and no annotations, so the description must explain return values and behavior, which it does (winning venue, fill, comparison). It also notes the dependency and error behavior, though it leaves ambiguous whether the swap executes or is only a routing computation, which matters given mutation siblings like place_order.

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

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

Schema description coverage is 100%, so the schema already documents `amount`, `into`, and the `venues` structure, making 3 the baseline. The description reinforces the amount format and symbol-based direction inference but adds little syntax or format meaning beyond what the schema provides.

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: 'best execution' routing for a DEX swap across a set of AMM pools, and spells out the exact return (winning venue, fill, per-venue comparison). This cleanly separates it from siblings like price_amm_swap (single-swap pricing) and amm_price_impact.

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

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

It implies the usage pattern ('give it the same notional and several venues') and lists supported venue types, so an agent can infer context. However, it never explicitly contrasts this with price_amm_swap or amm_price_impact or states when-not to use it, leaving routing 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?

With no annotations, the description carries the full burden and meets it: it discloses resource limits (CPU/memory/output rlimits, wall-clock timeout), the explicit non-isolation of filesystem and network, and the return payload (stats dict as JSON plus stdout). The 'Dispatch routing' paragraph further explains runtime behavior keyed on which hook the strategy overrides, including the loud-failure case.

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

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

Front-loaded with what it does, then usage, then the sandbox caveat, then a clearly labeled 'Dispatch routing' paragraph. Dense and largely waste-free, though the MVP-sandbox warning and dispatch details make it longer than typical; every clause still carries operational 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?

No output schema exists, and the description compensates by describing the return value (stats JSON + stdout). For a complex execution tool with runtime branching, resource caps, and a security caveat, all information an agent needs to call it safely and correctly is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: it specifies the expected CSV columns for the on_bar path, notes the 'STRATEGY = MyStrategy' entry-point alternative for strategy_code, and ties symbol/dataset semantics to the dispatch behavior. This goes beyond restating 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 (run) plus resource (a Python lrvx strategy against a CSV dataset) and the execution context (sandboxed subprocess). It is clearly distinguishable from siblings like validate_strategy, replay_window, and whatif, which do not execute a user-supplied strategy against a dataset.

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

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

Gives explicit triggering conditions ('try this strategy on my data', 'does this code actually work') and a clear when-not warning ('never aim it at untrusted code outside a developer's own machine'). It does not, however, name a sibling alternative for the validate-but-don't-run case, which validate_strategy or validate_strategy_no_lookahead would cover.

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?

No annotations exist, so the description carries the burden, and it does so well: it discloses the output shape (a canonical shell plus a Next steps section with docs_search queries) and the intended edit-after-scaffold workflow. It stops short of describing any failure modes or how validation is actually run, but for a pure code-generator with no mutation, this is strong coverage.

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

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

Front-loaded with the core purpose and the workflow trigger. It is on the longer side, but every sentence adds routing or parameter guidance rather than padding, so little is wasted.

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

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

With no output schema and no annotations, the description still covers what the tool returns, why the one required param matters, the parameter options, and how to proceed afterward. An agent has everything needed to call it correctly and act on the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains why language is required (polyglot bindings, don't guess for the user), lists supported values, and defines the three kind shapes (bar-driven = TA on bar close, trade-driven = tick-by-tick, hybrid = both) beyond the schema's terse enum list.

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 ('Return a starter lrvx strategy class') plus a concrete success criterion (compiles and passes validate_strategy). It is trivially distinguishable from siblings like validate_strategy, list_strategies, and get_example.

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 says this is the 'first' thing to write when the user asks to build a new strategy, and names the alternative behavior it replaces (writing lrvx bookkeeping from memory). It also states a prerequisite workflow ('ask which language they want first') and instructs following the returned Next steps in 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 no annotations provided, the description alone must carry behavioral disclosure. It reveals the dry-run default and its effect (dry_run=true default, explicit false applies the change), the engine-level scope (not per-account), and the refusal of paper tokens. This is substantial, but it does not mention side effects like audit logging (though the schema hints at reason recording), persistence across restarts, or failure conditions, which would make it complete.

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 with zero waste. The first sentence states the core action and behavior; the second covers the dry-run default, the use case, and the scope restriction. Information density is high and the most critical operational detail (scope refusal) is front-loaded at the end, keeping it memorable.

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 setter with three parameters, no output schema, and no annotations, the description covers all essential aspects: the state change semantics, the dry-run safety mechanism, the intended use cases, and the access scope restriction. Nothing an agent needs to correctly call the tool 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 only 33% (only reason has a description). The description directly explains the meaning and effect of the two undocumented parameters: active (true halts, false resumes) and dry_run (default true, explicit false applies). This fully compensates for the schema gap and adds decision-relevant semantics beyond the raw boolean types.

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 ('Set') and a precise resource ('engine's kill-switch state'), then immediately clarifies the effect of each boolean value. It distinguishes this from the sibling get_kill_switch by the write nature of the operation, leaving no ambiguity about what the tool does.

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 explicitly says 'Use for emergency halt and for resuming after manual review,' which is a direct when-to-use instruction. It also states a hard constraint: 'only live scope may call this -- paper tokens are refused even with dry_run=false,' which is critical operational guidance that the agent must know before invocation.

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 no annotations, the description carries the burden and does disclose two meaningful traits: it is a 'pure keyword heuristic; no LLM call' (deterministic, non-semantic matching), and it returns a 'ranked shortlist of real lrvx indicators'. It does not spell out the candidate payload or how ranking is scored, but the core behavioral character is conveyed.

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: what it does, when to use it, and the follow-up step. The trigger condition is front-loaded and no sentence is 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 no-annotation, no-output-schema tool the definition covers purpose, input examples, matching mechanism, and the required follow-up. The only gap is the shape of a returned candidate entry, which it partially deflects by pointing to `list_indicators`.

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

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

Schema coverage is already 100%, so the baseline is 3. The description earns a step up by giving sample valid inputs ('trend filter', 'momentum oscillator', 'volatility band') and by clarifying that the output is a ranked shortlist, which implicitly frames what the undocumented `k` count controls.

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+resource: 'Recommend lrvx indicators' from a natural-language intent description. It clearly distinguishes itself from list_indicators (canonical listing) and compute_indicator (evaluation) by framing itself as a phrasing-to-shortlist mapper.

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 trigger — 'when the user describes what they want without naming an indicator' — plus a concrete follow-up rule: always confirm shape with `list_indicators` after picking one. Both the when-to-use condition and the next-step alternative are 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?

With no annotations present, the description carries the full burden and does so reasonably: it discloses the analysis is static and explicitly states "Does NOT execute the code," which is the key safety property an agent needs. It also names the enforcement categories (forbidden patterns) beyond a bare claim of validation, though it does not describe rate limits, permissions, or failure 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?

Three short sentences: what it checks, when to use it, and the critical non-behavior. The check list is front-loaded, parenthetical examples are tight, and no sentence is 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 single-parameter, no-annotation validation tool, the description covers purpose, trigger point, and the non-execution guarantee. Since no output schema exists, it could have said more about what a failure result looks like (error location, hook diagnostics), which is the only meaningful 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 description coverage is 100% for the single 'code' parameter, and the description's mention of "Python lrvx strategy" and hook names aligns with rather than extends that documentation. Per the high-coverage baseline, this is a 3.

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 (static-analysis check on a Python lrvx strategy) and enumerates the concrete checks performed: AST parsing, required hooks (on_trade/on_bar), and forbidden patterns (eval, exec, __import__). An agent immediately understands the operation. It does not, however, differentiate itself from the sibling validate_strategy_no_lookahead, leaving that distinction to inference.

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

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

"Use this before running user-authored strategy code" states a clear precondition and context for invocation. There is no explicit when-not guidance or comparison against validate_strategy_no_lookahead, so routing between the two validators 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?

No annotations exist, so the description carries full burden. It discloses heuristic nature, false negatives, and specific patterns checked (AST walk, negative shift, forward-index, attribute names). However, it lacks mention of the return format or side effects (presumably read-only).

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?

Four sentences, no fluff, front-loaded with purpose. Every sentence adds value: purpose, method, patterns, limitations. Highly 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?

Given single parameter and no output schema, the description lacks a hint about what the tool returns (e.g., warnings list, success indicator). Also does not clarify whether it is state-modifying (should not be). Otherwise, it covers when to use and limitations.

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

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

Schema coverage is 100% with a basic description of 'code' parameter. The description adds significant context by explaining what kind of code (strategy module/class) and what patterns are analyzed, enriching the schema's minimal description.

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

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

The description clearly states it is a static-analysis check for lookahead bias, a specific bug. It uses a specific verb ('checks') and resource ('strategy code's AST'), and its name distinguishes it from the broader validate_strategy sibling.

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 provides clear usage context: 'Run before trusting any backtest result.' It does not explicitly exclude scenarios or mention alternatives, but the context is strong enough for an agent to decide when to invoke it.

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

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

With no annotations, the description must carry the burden of disclosing side effects. 'Counterfactual replay' and 'same as replay_window' imply a simulation, but it never explicitly states whether this is read-only, whether it can affect trading state, or what safety constraints apply. The examples hint at output (PnL), but not enough for full transparency.

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 concept, then practical examples. No filler or redundant phrasing, and the structure makes the tool's purpose immediately accessible.

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?

Given the tool's complexity (nested object param_overrides, no annotations, no output schema), the description provides meaningful context via examples and the replay_window reference. It doesn't explain the exact format of param_overrides or return values, but the examples partially cover that, making it reasonably complete for an experienced agent.

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 must compensate. It clearly explains 'strategy' as a filter and 'param_overrides' as the counterfactual changes, with illustrative examples. The time parameters (from_ts_ns, to_ts_ns) are implicitly covered by 'same as replay_window,' which adds semantic context beyond the bare 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 clearly states 'Counterfactual replay' and positions it as a specialized variant of replay_window with a strategy-name filter and required param_overrides. The concrete examples ('what if EMA period was 50 instead of 21') make the tool's purpose unmistakable and distinguish it from siblings.

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 says 'same as replay_window plus a strategy-name filter and required param_overrides,' which tells the agent exactly how this tool differs from the base replay tool. It also provides 'Use for' scenarios that specify when to invoke it, making the selection criteria clear.

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