midasflow-mcp-quickstart

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds rich behavioral detail: different endpoints per kind, what each returns (e.g., endpoint_weights map), and menu fallback. No contradictions.

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?

Every sentence adds value. Front-loaded with main purpose, then details each kind. No filler. Efficient 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?

Given the tool's complexity (three modes with different responses) and the presence of an output schema, the description fully explains the parameter, behavior, and use case. Nothing missing.

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

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

Schema coverage is 100% but description adds significant meaning: explains the effect of each 'kind' value ('account', 'usage', 'tiers') and the behavior when empty/unknown. Goes beyond the schema's brief 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?

Clearly states the tool returns the account view grouped by kind. Specific verb-resource pairing and explains each kind's purpose, distinguishing it from siblings like get_candles or analyze.

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

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

Explicitly states when to use: 'Read account/usage to self-throttle by your remaining quota.' Does not exclude alternatives, but the context makes it sufficient. Also mentions behavior for empty/unknown kind.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by disclosing cost implications (heaviest, more units, requires TOP tier), the route, and that it is not financial advice. No contradiction with 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 relatively concise with four sentences, front-loading the purpose. Every sentence adds value, though some phrasing (e.g., 'RIGHT NOW') could be considered redundant. Well-structured overall.

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 complexity and that an output schema exists (not shown), the description explains the output as a human-readable narrative combining multiple data sources. It does not cover error scenarios but provides sufficient context for the tool's heavy nature.

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 does not add extra detail beyond what the schema provides for the two parameters (symbol and lang). No parameter-specific elaboration.

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 produces 'the full MidasFlow AI-Analyst report for a symbol' and describes the synthesized narrative. It distinguishes itself from siblings by calling itself 'the HEAVIEST call' and directing to use after cheaper tools.

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

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

Explicitly says to call this tool 'sparingly, AFTER cheaper context tools,' providing clear usage guidance. However, it does not name specific alternative sibling tools, only 'cheaper context tools' generically.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds context beyond annotations by explaining that low-sample setups return directional bands (not errors) and that live results are gated. No contradiction with 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 concise, with each sentence adding value: purpose, nature, behavior, gating, route. It is front-loaded with the core action and efficiently covers all key points 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 the 6 parameters, 100% schema coverage, presence of output schema, and annotations, the description fully covers the tool's purpose, constraints (historical only, gating), edge case behavior, and relationship to siblings. No gaps for intended use.

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 does not add significant new meaning per parameter beyond summarizing required params as {symbol, entry, tp, sl}. It adds frame context but not detailed semantics.

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 setup over historical data, specifying the verb 'replay' and the resource 'setup over MidasFlow's 1m candle history'. It distinguishes from siblings like get_accuracy by mentioning the same frame, and contrasts with predictive tools by stating it is historical market 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?

The description explicitly labels it as a LAB/RESEARCH tool and notes it is historical data, not prediction. It explains behavior for low-sample setups and the gating behind ff:backtest_live, providing clear context for when to use. However, it does not explicitly list alternatives or 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?

The description reinforces the annotations by stating 'No network, no advice, 0 units' and 'pure local,' which align with readOnlyHint, idempotentHint, and destructiveHint. No contradictions; the description adds useful behavioral context beyond the annotations.

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

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

The description is two sentences long, concise, and front-loaded with key information (purpose, constraints, usage hints). 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?

For a simple calculator tool with full annotations, an output schema, and clear parameter details, the description provides sufficient context: what it does, how to use it, and its limitations (local, no network). No additional information 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 descriptions for each parameter are already present in the schema. The description adds a suggestion on where to source win_rate_pct ('Feed from a get_accuracy bucket win-rate'), but this is minor. Baseline 3 is appropriate as the description does not significantly extend the schema's meaning.

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 a 'pure local expected-value calculator' that takes win-rate and average win/loss percentages. It clearly distinguishes itself from siblings by noting it's local, no-network, and zero units, making the tool's purpose unambiguous.

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

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

The description provides explicit guidance on when to use the tool, e.g., 'Feed a get_accuracy bucket win-rate (or a score_symbol band).' It doesn't explicitly state when not to use, but the context of a simple calculator with limited input makes the usage clear.

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

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

The description adds behavioral context beyond the annotations, such as 'Model internals never exposed' and clarifying that win-rate is not realized PnL. Annotations already indicate read-only and idempotent behavior, so the description provides complementary nuance without contradiction.

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 paragraph that efficiently conveys key information, but it could be slightly more structured (e.g., bullet points for kinds) to improve scannability. It is not overly long and front-loads the main purpose.

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 presence of an output schema and rich annotations, the description adequately covers the tool's purpose and parameters. It could benefit from an example or more detail on return structure, but the combination with output schema makes this sufficient for most agents.

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?

All three parameters have full schema descriptions (100% coverage), but the tool description adds meaning by explaining the grouping by kind, defining each kind, and noting that empty kind yields a menu. This goes beyond the schema, which only lists defaults and 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 clearly identifies the tool as retrieving realized track-record (proof of edge) grouped by kind, with specific definitions for 'accuracy' (win-rate in the TP1 frame) and 'outcomes' (aggregate track-record). It distinguishes itself from sibling tools like get_signals or get_flow by focusing on accuracy/outcomes, providing a precise verb+resource.

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 when to use each kind and notes that an empty/unknown kind provides a menu, offering contextual guidance. However, it does not explicitly state when not to use this tool or provide direct comparisons to alternatives, leaving some ambiguity for the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds value by noting that a symbol outside the candle store returns an empty bars list (normal behavior) and includes the API route, providing behavioral context beyond 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 concise with two sentences. The first sentence states the core functionality and use cases, and the second adds edge-case behavior and the API route. No unnecessary words, and key information is 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 the tool's simplicity, full schema description coverage, comprehensive annotations, and presence of an output schema, the description is complete. It explains what the tool does, when to use it, and handles the edge case of an empty result for missing symbols.

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 covers all parameters with descriptions, achieving 100% coverage. The description reinforces the concept but does not add significant semantic meaning beyond what the schema already provides, such as details on range or format. Thus, a 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 retrieves OHLCV candle bars for a symbol at a chosen timeframe, explicitly noting it is the raw data from which other tools derive. This distinguishes it from sibling tools like analyze or get_signals.

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 lists use cases such as inspecting trend, range, volatility, volume profile, or feeding into custom indicators, providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or name alternatives, though sibling tools are listed separately.

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

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

Annotations already declare readOnlyHint, destructiveHint, etc. The description adds valuable behavioral context: it explicitly states the tool provides market data, NOT advice or a win-rate, and describes behavior for empty/unknown kind. No contradiction with 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 a single paragraph but well-structured: first sentence states purpose, then enumerates kinds, then adds a disclaimer. It is not overly verbose, though it could be slightly more concise while maintaining clarity.

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 (6 kinds, 2 parameters) and the presence of an output schema, the description covers all necessary aspects: each kind's purpose, symbol requirements, and behavior for empty/unknown kind. The disclaimer adds 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% with detailed parameter descriptions. The tool description adds extra context (e.g., 'market-wide, no symbol needed' for regime, 'normalized cross-exchange' for derivatives) and reinforces the relationship between kind and symbol, slightly enhancing semantic understanding.

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 provides contextual market reads grouped by kind, and lists each kind with a specific verb and resource (e.g., 'regime' for market-wide labels, 'phase' for entry-timing). It distinguishes itself from siblings by offering aggregated context across multiple dimensions.

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

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

The description implies when to use each kind (e.g., 'regime' when you need market-wide labels) and notes that empty/unknown kind returns a menu, but it does not explicitly compare to sibling 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?

Annotations already indicate readOnly, idempotent, not destructive. The description adds context: real-time nature, not advice, contested nature of VPIN, and the endpoint mapping per kind. This provides behavioral transparency beyond annotations without contradiction.

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 somewhat lengthy but front-loaded with the main purpose. Every sentence adds useful information, though it could be slightly more concise. Overall, it is well-structured and informative.

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 schema coverage, annotations, and that an output schema exists, the description is complete. It covers all kinds, default behavior, menu for empty kind, and important caveats about VPIN. No gaps are evident.

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 both parameters. The description reinforces the kind parameter by elaborating on each option and the menu behavior. It adds value but does not introduce new parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool returns per-symbol order-flow microstructure grouped by kind, with specific examples of each kind (vpin/all, cvd, sweeps, cross). It distinguishes the tool by focusing on microstructure and warns about VPIN, providing clear purpose 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 guidance on when to use (real-time context, not advice) and suggests pairing with get_accuracy for VPIN. It also explains behavior for empty/unknown kind (menu). However, it does not explicitly compare to sibling tools like get_market or get_signals, limiting alternative selection guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false. The description adds context beyond annotations: empty matrix is normal (not an error), and the data is not advice. This provides useful behavioral guidance.

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 route note, with no wasted words. It is front-loaded with the core purpose and includes essential clarifications 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?

With only one parameter and output schema indicated, the description covers purpose, behavior (empty matrix), data classification, and route. It is fully sufficient for an agent to understand the tool's function and output.

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 mentions 'a symbol' without adding new detail beyond the schema's description which includes case/space-insensitivity. The description does not enhance parameter understanding beyond what the schema already provides.

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

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

The description clearly states the tool provides a 'Liquidation-heatmap matrix for a symbol' with price levels where leveraged positions cluster. It distinguishes from siblings like get_candles or get_market by focusing on liquidation zones, and uses specific terms like 'price-magnet zones / liquidity pools'.

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

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

The description implies usage for anticipating price movement acceleration or stalling, and cautions it's 'Market DATA, not advice'. However, it does not explicitly state when to use this tool over alternatives like get_candles or get_orderbook, nor when not to use 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it's 'cheap,' 'top-level,' 'not advice,' and explains that empty/unknown kind returns a menu. No contradictions.

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 paragraph but is well-structured, starting with the main purpose, then detailing each kind, and ending with usage guidance. It is concise and every sentence adds value; could be slightly more structured but effective.

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 has 3 optional parameters and an output schema. The description covers the three modes, their endpoints, and the nature of the data. It addresses the empty kind case and notes the data is not advice. This is sufficient given the annotations and output schema.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains the grouping by kind, elaborates on each kind's content, and notes case/space-insensitivity for symbol. This provides useful context not captured 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 that the tool provides whole-market reads grouped by kind, with specific endpoints for movers, overview, and anomalies. It distinguishes from siblings by framing it as cheap top-level context before drilling into a single symbol.

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 says when to use: 'Cheap top-level CONTEXT to find what's MOVING before drilling into one symbol.' It implies exclusivity with 'before drilling into one symbol' but does not explicitly mention alternatives or when not to use. A more explicit exclusion would improve 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: cross-exchange aggregation, derived levels only, null fields for thin symbols, and route details. No contradiction with 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?

Two sentences plus a short note about routes. All sentences add value, no filler. Key information is 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?

With output schema present, the description covers the primary behavior and parameter effects. It explains that the response folds S/R when include_sr is true. Complete enough for a moderately complex tool with 3 parameters.

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. The description adds meaning: symbol is case/space-insensitive, include_sr defaults true, sr_timeframe defaults '1h'. It also explains how parameters affect the response.

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 provides a live order-book snapshot with bid/ask walls, book imbalance, spread, and folded support/resistance levels. It specifies the scope (cross-exchange aggregate, derived levels only) and distinguishes from siblings like 'get_market' or 'get_candles'.

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 when to use it ('see resting liquidity AND the level map in one call') and notes that thin symbols return null fields. It does not explicitly state when not to use or list alternatives, but 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable behavioral context: tier-gating, moat-scrubbing, market DATA nature, and anti-front-run delay for elite feed. These enrich transparency without contradicting 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 concise sentences that are front-loaded with the main action, then clarify quality modes and constraints. No wasted words; efficient and scannable.

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 availability of an output schema, the description does not need to explain return values. It covers quality modes, routes, and constraints. Missing explicit mention of pagination behavior (cursor parameter) is a minor gap, but overall adequate for the tool's 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 descriptions cover 100% of parameters, so baseline is 3. The description adds context for 'quality' (bucketed vs crown) and routes, but does not add significant meaning beyond what the schema already provides for other 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 pulls recent MidasFlow SignalEvent records, newest first, and explains the two quality modes (normal and elite) with distinct routes. However, it does not distinguish this tool from similar siblings like 'get_flow', missing a chance to differentiate purpose.

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

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

The description implies elite requires premium access and mentions tier-gating, but it does not explicitly state when to use this tool vs alternatives, nor provides when-not-to-use guidance. The guidance is implied but not explicit.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value by specifying that notional is banded, that liquidations use a rolling window, and that it provides 'market DATA, NOT a signal/advice', which clarifies behavior beyond 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 well-structured with a clear main clause and parenthetical details. It is somewhat dense but each sentence adds value. It could be slightly more streamlined, but the front-loading of the main purpose works well.

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 (all documented with 100% schema coverage) and an output schema (not shown but present), the description covers all behavioral aspects: kind differentiation, symbol requirements, window clamping, exchange filtering, and error handling. No gaps for an 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%, but the description adds meaning: it explains how 'symbol' behaves differently per kind (required for whales, empty for market-wide liquidations) and that 'window' is clamped to 1-300. It also clarifies that 'exchange' filtering applies only to liquidations.

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 provides 'Large-player / forced-flow intel' and breaks down two distinct kinds ('whales' and 'liquidations') with specific endpoints. It distinguishes from siblings (e.g., 'get_signals') by emphasizing this is raw market data, not signals/advice.

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 when to use each kind (symbol required for whales, empty symbol for market-wide liquidations) and error handling (empty/unknown kind returns menu). While it doesn't explicitly list when not to use it, the contextual sibling list and the 'not a signal/advice' note provide sufficient 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?

The description discloses behavioral traits beyond annotations: it folds a feed-safety check, returns null for most symbols, and the score is direction-agnostic while the plan is not. It also mentions idempotent and read-only aspects implicitly. No annotation contradiction.

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

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

The description is compact and front-loaded, stating the core functionality in the first clause. It packs a lot of information into two sentences, but the structure is slightly dense with semicolons and could be broken into bullet points for easier scanning.

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 an output schema exists and the tool has three parameters with 100% schema coverage, the description is complete. It explains null behavior, the relationship to calc_ev, the safety check folding, and the routing. No further information is needed for an agent to use 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?

Schema coverage is 100%, but the description adds significant context: symbol is case-insensitive, direction only affects plan ladder, include_safety triggers an extra API call. It clarifies that null is valid for most symbols. This enriches the parameter meaning beyond the 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 clearly states the tool returns a calibrated P(TP1) band plus a trade plan and feed-safety check for one symbol. It distinguishes itself from sibling 'calc_ev' by directing users to feed the band into that tool, and from generic 'get_signals' by specifying the data product.

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 when to use the tool (to obtain a calibrated score and safety check) and when not to use it ('never read it as buy/sell'). It clarifies that null returns are valid and not errors, and explains the direction parameter steers only the plan. While it mentions feeding into calc_ev, it does not contrast with other siblings like get_accuracy or get_flow.

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