flox-mcp

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

No annotations are provided, so the description carries full burden. It states the output is a table of average price and price impact, precise to the wei, and mentions a required dependency. However, it does not disclose read-only behavior, error conditions, or permissions.

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 plus a dependency note, with no wasted words. It front-loads the purpose and provides necessary input format details 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?

Given no output schema, the description explains inputs (pool and sizes) and outputs (price impact table). It is adequate but could include examples or mention error cases for 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?

Schema coverage is 100% for both parameters. The description adds clarity by specifying that sizes are 'NUMBER SYMBOL' strings and detailing the pool spec structure, going beyond the generic schema descriptions.

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 it provides a depth/slippage table for an AMM pool, listing realized average price and price impact for trade sizes. This is a specific verb and resource, and it clearly differentiates from sibling tools like price_amm_swap or compute_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?

The description advises using this tool to reason about how large a trade a pool can absorb before quoting. While it gives a clear usage context, it does not explicitly state when not to use it or list alternatives.

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 full burden. It discloses the default dry_run=true, but does not mention other behaviors like mutability, permissions, or irreversibility when dry_run=false.

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 no wasted words. The first sentence states the primary action; the second adds the default and context. Very well structured.

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 2 parameters and no output schema, the description is sufficiently complete. It explains the action, filtering option, default, and usage context. A minor gap is lack of clarity on the effect if dry_run=false.

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

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

Schema coverage is 50% (dry_run lacks description). The description adds 'Default dry_run=true,' which compensates for the missing schema description. For symbol, it adds no new meaning beyond the schema.

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

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

The description clearly states 'Cancel every open order, optionally filtered by symbol.' It uses a specific verb (cancel) and resource (open orders), and the filtering distinguishes it from cancel_order, which cancels a single 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 calls it 'The most common panic stop primitive after set_kill_switch,' providing context for when to use it. However, it does not explicitly state when not to use it or compare to alternatives like cancel_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?

No annotations are provided, so the description carries the full burden. It discloses that the tool communicates via HTTP to a local ControlServer and that dry_run defaults to true. However, it does not specify destructive behavior (order cancellation is irreversible), authentication requirements, potential errors, or rate limits. Additional behavioral context would improve 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?

The description is extremely concise, consisting of two short sentences that convey all essential information. It front-loads the primary action and immediately adds key behavioral notes. No superfluous 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?

Despite no annotations or output schema, the description covers the core functionality, usage context, default behavior, and internal mechanism. It lacks information on error handling and return values, but for a simple cancellation operation, the provided details are largely sufficient for agent invocation.

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 zero description coverage, leaving the description to explain both parameters. It clarifies that order_id identifies the order and that dry_run defaults to true, adding meaning beyond the schema. It does not specify constraints like order_id format, but given the low schema coverage, the description compensates effectively.

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', the resource 'one open order', and the method 'by id'. It directly contrasts with the sibling tool 'cancel_all' which cancels all orders, providing strong differentiation.

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 specific use cases: 'operator-driven cleanup or panic stop'. It also mentions the default dry_run behavior. While it does not explicitly exclude other scenarios or compare with alternatives, the context is sufficient for an agent to understand when to invoke this tool.

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

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

Discloses important constraints (1 MiB cap, flox-py dependency) and implies a read-only compute operation, but does not explicitly state whether it has side effects or error behavior. With no annotations provided, the description bears the full burden.

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, each adding value: purpose, usage guideline, input cap, dependency. No fluff, well front-loaded.

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

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

Given no output schema and simple params, the description covers when to use, constraints, and dependency. However, it omits the return format, which could help an agent interpret results.

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

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

Schema coverage is 100% and already describes both parameters (name, data) in detail. The description adds context about extra parameters (window/period/smoothing) but does not enhance semantics of the required params 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 the tool runs a single FLOX indicator over a list of floats and returns output, distinguishing it from sibling tools like list_indicators 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?

Explicitly advises using it for sanity-checking indicator behavior on small arrays before strategy integration, especially for indicators with non-obvious parameters. Also notes input cap and optional dependency.

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 carries full burden. It explains query syntax (AND matching, phrase, operators), indexing scope (strict allowlist, private files never indexed), and gives canonical queries. However, it does not mention whether the docs are from a fixed snapshot or live, or any rate limits.

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

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

The description is well-structured: it starts with a concise purpose statement, then details query syntax, and ends with canonical workflow queries. Every sentence adds necessary information, and there is 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?

Given that the tool has only two parameters and no output schema, the description is complete. It covers what the tool searches, how to form queries, when to use it, and common use-case examples. No significant gaps.

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

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

Schema coverage is 100% as both 'query' and 'k' are described with types and default. The description adds value by elaborating on query syntax (e.g., 'Wrap a phrase in double quotes for exact match') and providing example queries, which goes beyond the schema's basic descriptions.

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 performs 'Top-k full-text search over the FLOX documentation' and lists specific types of documents it covers. It distinguishes itself from sibling tools by focusing on documentation grounding rather than other actions like order placement or strategy validation.

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 tells the agent to use this tool 'whenever the user asks 'how do I X' / 'what does Y do' / 'where is Z documented'' and provides canonical workflow queries mapping common user intents to specific search terms. It also contrasts with relying on training data.

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?

No annotations provided, so description carries full burden. Describes what it does but lacks disclosure of edge cases (e.g., both parameters given, unmatched dict). Adequate 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?

Three tightly focused sentences: purpose, input details, usage hint. No wasted words, front-loaded.

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

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

Given no output schema, description specifies return structure (name, type, units, description). Lacks detail on error handling or output format, but sufficient for agent to understand capability.

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%, but description adds meaning by clarifying the OR relationship between type_name and event, and explaining matching behavior when type_name is omitted.

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

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

Clearly states 'Describe the fields of a FLOX event struct' with specific verb and resource. Distinguishes from sibling tools like get_event_log by focusing on structural explanation.

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?

Includes explicit usage hint: 'Use when the user asks what's in this event.' Provides clear context without exclusions.

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

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

No annotations provided. Description reveals default dry_run=true and that market orders are used, but does not disclose potential side effects like slippage or market impact.

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 purpose, no redundant 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 2-param tool with no output schema, description covers purpose, filtering, and default. Could mention confirmation behavior, but 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?

Description adds 'optionally filtered by symbol' and 'Default dry_run=true' beyond schema. Schema already describes symbol well, but dry_run semantics are minimally covered.

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?

Description clearly states 'Close every open position with opposite-side market orders, optionally filtered by symbol.' This is a specific verb-resource combination that distinguishes from siblings like cancel_all or cancel_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?

Explicitly says 'Use for close everything operator actions or end-of-day flatten.' Provides context, though does not explicitly exclude other scenarios or compare with alternatives.

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 provided, so description carries full burden. Discloses that the tool is 'Cheap; pure bundled text' and 'Cuts the AI-agent cycles spent rediscovering what the surface is on every fresh session.' This is sufficient for a non-destructive, static 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?

Concise, well-structured, front-loaded with the key instruction. Every sentence adds value 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?

Complete for a no-parameter, no-output-schema tool. Covers purpose, when to use, and expected content. No gaps.

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

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

No parameters exist (schema coverage 100%), so description adds no parameter info. Baseline is 4 for zero-parameter tools.

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?

Explicitly states the tool's purpose: 'Call this FIRST when you don't know which FLOX MCP tool to use.' Clearly differentiates itself from siblings by being the orientation tool. Provides specific details about the output (Markdown narrative organized by categories).

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 when-to-use guidance: 'Call this FIRST' and 'when you don't know which FLOX MCP tool to use.' Implies it should be used before exploring other tools. No alternative exclusions needed.

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

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

With no annotations, the description carries the full burden and does well. It discloses that the tool takes no arguments, is 'Cheap; pure bundled text,' and returns a specific Markdown guide listing contents. This gives a clear behavioral profile without hiding side effects or requiring inference.

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 use case, then provides a concise but informative breakdown of what the guide contains and the exclusion. Each sentence earns its place; no filler or repetition. It is appropriately sized for the complexity of a no-argument guide tool.

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

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

Despite lacking an output schema and annotations, the description is self-sufficient. It explains the guide's contents and the tool's context, and since it is a static informational resource, there are no side effects or return values left unexplained. The exclusion to run_backtest also gives the agent enough context to choose correctly.

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

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

The tool has zero parameters, and the schema already reflects that with an empty properties object. The description adds 'No arguments,' which is redundant but harmless. According to the baseline for 0 params, a score of 4 is appropriate; there is nothing substantive to add.

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 explicitly states the tool's purpose: 'Returns a Markdown guide to the optional FLOX venue module' and opens with 'Use when the user wants to BUILD A MARKET rather than trade on one.' It clearly distinguishes this from trading tools and specifically names an alternative (run_backtest) for the excluded case, so it is unambiguous versus 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?

Usage guidance is explicit: it lists concrete scenario examples (simulate agents, model market impact, run matching engine) and gives a clear exclusion with a suggested alternative: 'NOT for an ordinary single-strategy backtest over historical data -- use run_backtest.' This meets the highest bar for when-to-use and when-not-to-use.

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?

With no annotations, the description carries the full transparency burden. It adds useful context about the quality of the examples (canonical, CI-validated), but it does not disclose potential error behavior, output format, or access requirements. For a simple read-only retrieval tool, this is a partial disclosure but lacks some operational details.

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, each serving a distinct purpose: stating the core function, providing usage guidance, and listing the parameter enums. It is front-loaded with the primary action and contains no redundant or filler text.

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 adequately covers purpose, usage, and parameters. It stops short of explicitly stating the return format or error conditions, but the nature of 'example code' is clear. The absence of annotations and output schema makes it slightly less complete than a tool with richer metadata.

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 for both parameters, listing the exact enum values for topic and language. The description repeats these values without adding new syntax or format details. The example query mapping is helpful for usage but does not enhance parameter 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 uses a specific verb ('Return') with a clear resource ('canonical FLOX example code') and scope ('for a topic, filtered optionally by language'). It also explicitly lists the valid topics and languages, distinguishing this tool from siblings like docs_search or scaffold_strategy by emphasizing the CI-validated, canonical nature of the examples.

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 this when the user asks show me how to...') and provides a clear directive to prefer these examples over writing fresh code, with a rationale (CI-validated vs. generated code). This gives the agent strong guidance on when to invoke this tool and when to avoid generating code from memory.

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?

With no annotations, the description fully carries the burden. It discloses the read-only nature, snapshot path logic, the special 'not_running' state, and return structure. Could mention rate limits or concurrency, but overall strong.

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 a single dense paragraph that front-loads the purpose. It is concise but could be better organized with bullet points for the return format and special cases.

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 provides the complete return JSON structure and explains the pre-engine state. Parameters are fully covered, and the snapshot mechanism is clarified. No gaps remain.

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 explaining the state_path parameter's fallback to FLOX_RUNTIME_STATE env var and that account/strategy are filters, elevating it above the schema alone.

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 starts with a specific verb+resource: 'Read positions' and provides example user queries. It explicitly states read-only behavior, distinguishing it from sibling mutation tools like flatten_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?

The description gives clear when-to-use examples ('what's in my positions') and explains the snapshot prerequisite. It lacks explicit when-not-to-use or alternatives, but the context is sufficient.

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

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

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 provided, the description carries the full burden, and it does well by disclosing templates, output behavior ('Result includes the CLI output and a Next steps section with `docs_search` queries'), and the wrapper nature. However, it lacks details about failure conditions such as behavior if the target directory already exists or if names are invalid beyond the snake_case note. This is a minor gap but not misleading.

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 concise yet information-dense, with each sentence serving a purpose: purpose, wrapper context, usage triggers, template details, and return value. It is well-structured and front-loaded with the core action, making it easy for an agent to parse quickly. No filler or redundant phrasing.

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 covers expected results ('CLI output and a Next steps section'). It also provides enough context about templates and naming to make the tool usable without external knowledge. The description fully compensates for missing structured metadata, making it complete for its 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?

The input schema already has 100% coverage, but the description adds significant semantic value. It elaborates each template with concrete contents (e.g., 'research' includes 'notebook + sample data + main.py') and clarifies that `project_name` special characters become snake_case in `__PROJECT_SLUG__`. This goes beyond the schema's minimal descriptions and helps an agent select appropriate values.

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

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

The description opens with a specific verb+resource statement: 'Create a new FLOX project from a bundled template.' It also notes this is a 'thin wrapper around the canonical `flox new` CLI', which clarifies its limited scope and distinguishes it from the broader `flox` CLI and sibling tools like `scaffold_strategy`. The purpose is immediately evident.

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 with concrete user intents: 'Use when the user asks "set up a new flox project" / "I want to scaffold a research notebook" / "start a live trading bot".' This provides clear invocation criteria. It also mentions that the CLI remains the source of truth, implying the MCP tool is for discoverability and simple use cases, which guides the AI agent toward the appropriate pathway.

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 adds the case-insensitive filter behavior, which is useful, but does not explicitly state read-only nature, auth needs, or error behavior. The 'enumerate' verb implies safety, but it is not explicit.

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 that front-load the purpose, then provide usage guidance and a behavioral note. 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 simple enumerator with no output schema and no annotations, the description covers purpose, usage, and a key filter behavior. It is slightly incomplete due to the missing differentiation from list_capi_functions and the cpp surface omission.

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 baseline is 3. The description adds the case-insensitive filter detail beyond the schema, but it also omits the 'cpp' surface listed in the schema's language enum, creating a potential inconsistency.

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 enumerates public exports of a binding surface, with a specific verb and resource. It lists the surfaces but does not explicitly differentiate from the sibling tool list_capi_functions, which overlaps on the C-API surface.

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 use cases are given ('what does the {Python|Node|Codon} binding expose?', 'browse a binding before picking a symbol'). However, it does not mention when not to use it or alternative tools like list_capi_functions, so it lacks 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 provided, the description carries the burden of behavioral disclosure. It reveals that the tool reads from a 'committed ABI snapshot' (implying possible staleness) and returns a well-defined set of signature components. It does not explicitly state read-only, but the read-only nature is strongly implied by 'Search' and 'Returns'.

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 extremely concise: two sentences that front-load the purpose and then provide usage guidance. Every word adds value without any redundancy or 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?

The tool is simple (two optional params, no output schema), and the description covers the core purpose, usage context, and return content. It could be slightly more complete by showing an example output shape, but it is adequate for an agent to invoke the tool correctly.

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

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

The input schema already provides 100% coverage for both parameters (limit and filter) with clear descriptions. The tool description adds no additional parameter semantics beyond what the schema already offers, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: searching the FLOX C-API surface and returning name, return type, and parameter types for every exported flox_* function. It uses a specific verb ('Search') and resource ('C-API surface'), and distinguishes from siblings like lookup_symbol by focusing on the complete list of exported symbols.

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: when the user is writing FFI code (Codon, QuickJS, Rust cgo, ctypes) or asks 'what C symbols can I call'. While it does not mention specific alternatives or exclusions, the given context is clear enough to guide selection among sibling 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?

With no annotations, the description carries the full burden. It discloses what is returned (class signature, batch function, shape), implying a read-only listing operation. It does not explicitly state side-effect freedom or performance characteristics, but the simple list nature makes these omissions minor.

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

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

The description is two sentences: the first states the tool's purpose and output contents, the second provides usage context. Every word earns its place, with no redundancy or 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 simple list tool with one optional parameter, the description adequately covers the expected output and use context. The output schema is absent, but the description enumerates the key fields (class signature, batch function, shape), making the tool's behavior sufficiently clear for an 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 description coverage is 100% for the single 'filter' parameter, so the baseline is 3. The description adds no further meaning to the parameter; it only says 'case-insensitive' in the schema, which is sufficient. No extra semantic value beyond the schema is provided.

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 uses a specific verb ('List every indicator') and resource ('FLOX Python binding') and clearly distinguishes the tool's scope by detailing the returned fields (class signature, batch function, shape). It also positions itself relative to user intent, separating it from sibling tools that focus on specific indicators or other 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?

The description explicitly tells when to use it: 'when the user asks what indicators does FLOX support' or 'before suggesting an indicator name.' This gives clear context but does not name alternatives or exclusions, so it stops short of the full 'when/when-not/alternatives' 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?

No annotations provided, so the description carries full burden. It declares the tool is read-only and describes what it returns. For a simple listing tool with no parameters, this is sufficient transparency, though it could mention error handling or empty result 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?

Two concise sentences with front-loaded purpose. No unnecessary words, and every sentence adds value. 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?

The description explains the return values (name, status, symbols) despite the absence of an output schema. For a simple listing tool with no parameters, this provides complete contextual information for an AI agent to understand what the tool returns.

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 schema coverage is 100%. According to guidelines, baseline is 3. The description adds no parameter-specific information because there are none.

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 lists strategies with specific attributes (name, status, subscribed symbols). It effectively distinguishes from sibling tools like get_strategy_state by specifying that it lists all known strategies and their properties.

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 explicit usage cues: 'Use when the user asks "what's running" / "which strategies are active"' and declares the tool is read-only. It does not explicitly exclude alternative tools but gives clear context for 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 carries the burden. It discloses the output format (full Markdown documentation page) and content areas (fix recipe, common causes, diagnostics). It doesn't mention error behavior for invalid codes, but for a read-only lookup this is acceptable and adds meaningful context.

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

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

Two sentences, front-loaded with the core purpose and output, followed by a usage directive. Every phrase earns its place; no redundancy or fluff.

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 tool with a single parameter and no output schema, the description explains what it returns (full Markdown page), when to use it, and provides a concrete example. It is self-contained and sufficient for correct invocation.

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

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

Schema coverage is 100% and the description essentially repeats the example ('E_SYM_001') without adding new meaning beyond the schema. Baseline 3 applies; the description doesn't enrich the parameter beyond its existing schema documentation.

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 verb 'Resolve' with the specific resource 'FLOX error code' and gives an example ('E_SYM_001'). It also lists output content (Markdown documentation page with fix recipe, causes, diagnostics), distinguishing it from generic docs_search or lookup_symbol 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?

Provides explicit when-to-use ('whenever a FloxError is raised in user code') and when-not-to-use ('never guess at a fix from the message alone'). This is direct usage guidance, though it doesn't name alternative tools, the context is clear 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?

With no annotations provided, the description fully carries the transparency burden. It discloses return structure, handling of methods as Owner.method, acceptance of arbitrary spellings, and the presence of a '## Gotchas' section for semantic pitfalls. This gives the agent a solid understanding of what to expect.

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 well-structured and front-loaded with the core purpose, then return, usage, matching behavior, and gotchas. Every sentence adds distinct value with no redundancy or filler. It is concise yet comprehensive.

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 lack of an output schema, the description explains return fields (local name, kind, signature), input flexibility, and special notes (gotchas). For a cross-language lookup tool, this covers all necessary aspects an agent would need to select and invoke it correctly, and to interpret the result.

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

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

The schema already covers both parameters with descriptions (100% coverage), so baseline is 3. The description adds meaningful extras: case-sensitivity, automatic spelling transformations, examples, and guidance on when to use the language filter. This enriches the semantic meaning beyond the schema, earning a 4.

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

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

The description states a clear, specific action: 'Resolve a FLOX symbol across every surface' and details the return value (local name, kind, signature). It clearly distinguishes from sibling tools like lookup_error_code or list_capi_functions by focusing on cross-language symbol resolution.

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 when-to-use guidance: 'Use this whenever the user names a struct, function, or indicator... never guess at the cross-language spelling.' It also explains when to use the language filter. However, it does not explicitly name alternative tools or state when not to use it, stopping just short of a perfect score.

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?

Without annotations, the description adds value by disclosing HTTP communication with local ControlServer, env var requirements, and dry-run behavior. However, it doesn't cover error handling, rate limits, or response behavior, leaving some gaps.

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, each adding value with no redundancy. The key actions and constraints are front-loaded, making it easy to parse quickly.

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 architecture, authentication, dry-run behavior, and approval flow for an order placement tool with 9 parameters. Missing explicit return value or error cases, but the complexity is adequately handled.

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%, so baseline is 3. The description does not add further meaning to parameters like symbol or qty beyond what the schema provides, but it does explain the role of dry_run and approve_token in 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 description clearly states the tool places an order via the flox engine, specifying the resource (order) and verb (place). It differentiates from sibling tools like cancel_all and cancel_order by focusing on order entry, and adds specificity with 'manual hedges or operator-driven order entry'.

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

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

The description explains default dry_run=true and the need for approve_token in live scope, guiding when to use the tool. It provides context but does not explicitly list alternatives or when not to use it, though sibling context helps.

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 provided, so description carries full burden. Discloses key behaviors: exact to wei, lossless for 256-bit values, and required dependency 'flox-py'. Does not mention rate limits or side effects, but as a read-only pricing tool, this is acceptable.

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

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

Four sentences, front-loaded with purpose, no fluff. Every sentence adds essential 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?

Adequately describes inputs and use cases for a complex tool with nested objects and no output schema. Lacks mention of return value (likely amount_out), but context is sufficient for an AI agent to infer behavior.

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%, but description adds valuable context: explains that amounts are decimal strings in native wei/lamports, lossless, and breaks down pool parameter structures per venue. Goes beyond schema descriptions.

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?

Clearly states the tool's purpose: pricing a DEX swap against various AMM pool types with exact precision (wei-level). Differentiates from sibling tools like 'route_amm_swap' 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?

Explicitly describes when to use: to quote a fill or measure price impact on constant-product, Raydium CP, or Uniswap v3 pools. Also mentions the required dependency. Lacks explicit exclusions but context is clear.

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

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

No annotations are provided, so the description carries full burden. It explains the underlying commands for each mode (CLI vs Python script) and the result format. It does not mention side effects like overwriting existing files, but it is transparent about the general behavior.

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

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

The description is concise with about five sentences, each serving a clear purpose: first states the tool's function, then explains modes, then gives usage examples, and ends with the result. 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?

Given 9 parameters, no output schema, and no annotations, the description provides adequate context for an agent to understand when and how to use the tool. It covers the high-level workflow and result usage. It lacks details on error handling or permissions, but is fairly complete for its 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 coverage is 100%, so each parameter already has a description. The description adds value by grouping parameters under modes and explaining the purpose of each mode, but it does not significantly enrich individual parameter semantics 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 the tool captures market data into a .floxlog tape, distinguishes between live and historical modes, and gives concrete examples of user requests that trigger it. It is easily differentiated from sibling tools which cover orders, strategies, 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 explicitly states when to use the tool with examples like 'record some BTC data' or 'pull a month of klines'. It does not explicitly mention when not to use, but the context is clear and the tool's purpose is well-defined 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?

The description explains the output (price, reserves, LP-value, impermanent-loss, drift series) and mentions the optional dependency. It does not disclose potential side effects or performance implications, but for a read-only replay tool, the behavioral coverage is good.

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 with no redundancy. The first sentence states the main action, the second details outputs, and the third gives use case and dependency. It is front-loaded and every sentence is valuable.

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 absence of an output schema, the description compensates by listing return values. It also explains the relationship between parameters. However, it could mention potential data format errors or the compute-intensive nature of replaying many swaps.

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

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

The description adds significant meaning beyond the schema: it explains that 'swaps' and 'evm_logs' are mutually exclusive, describes the format of evm_logs (data word order), and clarifies that 'pool' is the starting state. With 100% schema coverage, this description provides essential guidance.

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 backtests a DEX position from recorded pool history by replaying swaps. It distinguishes itself from siblings like 'run_backtest' by specifying the use of recorded transcript, and from 'amm_price_impact' by focusing on time series evaluation.

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 tells when to use it ('evaluate an LP position or trading sequence against a real transcript') and mentions a dependency requirement. However, it does not explicitly state when not to use it or compare to alternatives like 'run_backtest'.

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?

Description discloses exact-to-wei precision, input format for amounts, error behavior on mis-routing, and the optional dependency. It lacks clarity on whether the swap is simulated or executed, but given the sibling list includes place_order, it likely simulates. No annotations provided, so description carries the burden.

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?

Description is concise with four sentences. It front-loads the main purpose and includes important details. Slightly dense but no unnecessary 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?

Description adequately covers inputs and outputs, but the return value ('the fill', 'per-venue comparison') is somewhat vague. No output schema, so more detail would help. Overall sufficient for a routing tool but not fully explicit.

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 descriptions for all three parameters. Description reiterates the amount format and venue structure but adds minimal value beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool performs best execution for DEX swaps across AMM pools. It specifies that it returns the best venue, fill amount, and per-venue comparison. This distinguishes it from siblings like price_amm_swap 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?

Description implies usage context: provide the same notional and multiple venues to get the best fill. It mentions error handling for mis-routed swaps and a dependency requirement. However, it does not explicitly contrast with similar tools or state when not to use this tool.

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

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

Discloses resource limits (CPU, memory, output size, wall-clock timeout), lack of filesystem/network isolation, return format (JSON plus stdout), and internal dispatch routing based on strategy hooks. No annotations provided; description fully covers behavioral traits.

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?

Concise at ~150 words, front-loaded with core action, every sentence adds value: purpose, usage, safety, return, routing. No redundancy or fluff.

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 purpose, usage, safety, return behavior, internal routing, and parameter constraints. Despite lacking output schema, it describes the return structure. Suitable for the complexity of running arbitrary code.

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?

Adds defaults (symbol BTCUSDT, wall_timeout_s 60), constraints (dataset_path capped at 64 MiB), and explains strategy_code expects a flox.Strategy subclass or STRATEGY variable. Describes dispatch logic tied to parameter use. All 4 parameters have schema descriptions, but description enriches them.

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

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

Description clearly states it runs a Python FLOX strategy against a CSV dataset in a sandboxed subprocess, specifying verb, resource, and environment. It distinguishes from sibling tools like validate_strategy by emphasizing its purpose for testing strategies on data.

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 tells when to use: 'when the user asks try this strategy on my data or does this code actually work'. Includes a strong warning against untrusted code, but does not directly mention 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 full burden. It discloses that the output compiles and passes validate_strategy, includes Next steps with docs_search queries, and mentions supported languages and kinds. No contradictions, but it could mention lack of side effects.

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 purpose and has clear sections for usage, language, kinds, and next steps. Each sentence adds value, though it could be slightly more concise with bullet points.

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 and lack of output schema, the description covers the essential: what it does, when to use, required input, and output context (Next steps). It is sufficient for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by enumerating language options (python, node, codon, quickjs) and strategy shapes (bar-driven, trade-driven, hybrid) beyond the schema's enum descriptions.

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 starter FLOX strategy class that compiles and passes validate_strategy. It specifies verb 'Return' and resource 'starter FLOX strategy class', and distinguishes from siblings like validate_strategy 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 'use this as the *first* thing you write when the user asks to build a new strategy' and instructs to ask the user for language before calling. Also provides alternatives: 'instead of writing the FLOX bookkeeping from memory'.

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 discloses key behaviors: active=true halts all trading, active=false resumes, and the dry_run default and effect. It clarifies that dry_run=false applies the change. It does not cover permissions or audit log details, but the core behavioral nuance 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 three sentences, front-loaded with purpose, then parameter semantics, then usage. Every sentence adds value with no fluff.

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 simplicity, the description covers the core behavior, required parameter, and dry_run nuance. It doesn't mention return values or the reason parameter beyond what the schema provides, but the essential context for selecting and invoking the tool 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 only 33% (reason only), but the description adds meaningful semantics for active (true halts, false resumes) and dry_run (default true, explicit false applies the change). This compensates for the schema gap on two of three parameters.

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

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

The description clearly states the tool 'Set the engine's kill-switch state' with a specific verb and resource. It distinguishes from siblings like get_kill_switch (getter) and cancel_all/flatten_positions (other emergency tools) by focusing on halting and resuming trading.

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

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

The description gives explicit usage context: 'Use for emergency halt and for resuming after manual review.' However, it does not mention when not to use it or directly name alternative tools, so it falls short of the 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?

No annotations provided, so the description carries full burden. It discloses the tool is a 'pure keyword heuristic; no LLM call' and instructs on follow-up action, providing clear behavioral context.

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

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

Three focused sentences: purpose with examples, usage context, and behavioral note. No wasted words, front-loaded with key 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?

Given two parameters and no output schema, the description covers purpose, usage, behavior, and follow-up. The output is implied as a 'ranked shortlist' of indicators, which is sufficient for the tool's 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?

Schema coverage is 100% with good parameter descriptions. The description adds value by listing the specific categories the 'description' parameter maps to, which 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 states clearly that the tool recommends FLOX indicators based on an English description of user intent, listing example categories and distinguishing itself from sibling tools like 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?

Explicitly says when to use ('when the user describes what they want without naming an indicator') and provides post-use guidance ('Always confirm shape with list_indicators after picking one').

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 carries full behavioral burden. It is transparent about the safety profile: 'Does NOT execute the code' and details the checks performed (AST parse, hook presence, forbidden patterns). This fully discloses the tool's behavior without relying on 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?

The description is three compact sentences: what it does, when to use, and what it doesn't do. Every sentence earns its place with no redundancy or fluff. It is extremely concise and well-structured.

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 one-parameter validation tool with no output schema and no annotations, the description is quite complete. It covers purpose, usage, and non-execution. However, it does not specify the return format or error behavior, which would be useful given no output schema exists. Slight gap prevents a perfect score.

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

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

Schema coverage is 100% and the parameter 'code' is already described as 'Python source for the strategy module/class.' The description adds minimal extra meaning by calling it a 'Python FLOX strategy' and 'user-authored strategy code,' but does not significantly enhance parameter semantics beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs a 'Static-analysis check on a Python FLOX strategy' with specific behaviors: AST parses, hooks present, no forbidden patterns. It distinguishes from sibling tools by emphasizing it does not execute code and is specifically for pre-run validation, making it specific and 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 explicitly says 'Use this before running user-authored strategy code,' providing a clear when-to-use context. It does not mention alternatives or exclusions, but the guidance is strong enough for typical selection. A minor gap is not contrasting with similar sibling like validate_strategy_no_lookahead.

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.