midasflow-mcp-quickstart

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral context: it explains the three 'kind' endpoints, the distinction between them, and what each returns (e.g., 'endpoint_weights map' for usage). No contradictions 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 well-structured and concise. It front-loads the core purpose ('Your mf_ key's account view'), then uses bullet-like clarity to list the three kinds. Every sentence adds value—no fluff or repetition. Despite moderate length, it is 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 the presence of an output schema (not shown but noted), the description covers all necessary context: what the tool does, the three possible views, their API endpoints, and the purpose of self-throttling. It is complete for a read-only informational 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 only parameter 'kind' is fully documented in both the schema and description. The description goes beyond the schema by explaining each enum value's meaning, the default behavior ('account' if empty/unknown leads to a menu), and mentions specific endpoints, which provides rich semantic 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 it provides the account view for the mf_ key, grouped by 'kind', and lists the three specific sub-views (account, usage, tiers) with their corresponding API endpoints and a brief summary of what each returns. It uses a specific verb ('read') and identifies the resource ('account / usage / tiers'), 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 explicitly advises using the tool to 'self-throttle by your remaining quota', which is a clear use case. It also explains the behavior for empty/unknown kind. However, it does not explicitly exclude alternative tools or describe when not to use it, but the context signals and sibling list (e.g., 'analyze', 'backtest') imply this is the only tool for account/usage/tier information.

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 read-only, idempotent, and non-destructive behavior. The description adds that it composes many sub-feeds, is the heaviest call, and costs more units, offering valuable 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 extremely concise, using bold for emphasis, and front-loads critical information. Every sentence adds value, with no repetition 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?

Given the complexity of the tool (heavy AI-Analyst report with multiple sub-feeds), the description covers purpose, usage order, cost tier, and disclaimer. An output schema exists, so return values need not be explained. The description is fully sufficient for selecting and invoking 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%, so the schema already documents both parameters. The description does not elaborate on parameter details, but it implies the symbol is the main input. A baseline score of 3 is appropriate as the description adds minimal value 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 identifies the tool as the full AI-Analyst report for a symbol, synthesizing multiple data sources into a human-readable narrative. It distinguishes itself from sibling tools by calling itself the 'heaviest' call, which is unique among the listed 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?

Explicitly advises to use sparingly, after cheaper context tools, and notes higher cost and top-tier requirement. It also cautions that output is not financial advice, providing clear usage 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?

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context: it emphasizes the tool outputs historical data, not predictions; explains the first-touch TP1 frame; and clarifies that timeout anchors are excluded from probability calculations. This goes beyond the annotations to describe edge case handling and the nature of results.

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

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

The description is 5 sentences, front-loaded with the core purpose. It uses caps for emphasis ('DATA', 'NOT') which is slightly informal but not detrimental. The route hint is included but not essential. It could be trimmed slightly, but overall it's 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 presence of an output schema (so return values need not be explained), the description covers key aspects: the historical frame, live gating, low-sample behavior, and timeout handling. It does not mention error conditions or symbol validation, but these are partially covered by the schema descriptions. Considering tool complexity, it is fairly complete.

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 6 parameters have schema descriptions, but the description adds critical context beyond them: it explains that direction is inferred from tp/sl relative to entry, that tp can be an ordered list, and that max_hold_min clamping excludes timeouts from probability. This enriches the agent's understanding of how parameters interact and affect results.

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 replays a trading setup over historical candle data to compute P(TP1 before SL) and EV. The title reinforces this by labeling it 'Backtest a setup' and specifying the output metrics. It distinguishes from sibling tools like 'calc_ev' and 'get_accuracy' by focusing on historical replay rather than real-time or aggregated metrics.

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 labels the tool as 'LAB / RESEARCH', signaling experimental use, and warns that live results are gated behind a feature flag. It also notes that low-sample setups return a directional band instead of an error. However, it does not explicitly compare to sibling tools like 'calc_ev' or 'get_accuracy', leaving the agent to infer when to use this rather than those. Slight markdown for lacking explicit 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds 'pure local', 'No network, no advice, 0 units,' which reassures agents of safety and no side effects. No 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?

Two sentences with no redundancy: first sentence states purpose and location, second sentence adds usage guidance. Every word contributes value.

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 is sufficient. The presence of an output schema further reduces the need to explain return values. Context about feeding from other tools is provided.

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%, but description adds value by advising 'Feed from a get_accuracy bucket win-rate' for win_rate_pct and noting 'Sign is ignored' for avg_loss_pct, which clarifies usage beyond 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?

Description clearly states it is a 'pure local expected-value calculator' using win-rate and win/loss percentages, and explicitly notes 'No network, no advice, 0 units.' It distinguishes itself from sibling data-retrieval tools like get_accuracy by instructing to feed its output into this calculator.

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 provides context on when to use (reason about expectation per trade) and explicitly mentions feeding from get_accuracy or score_symbol. Does not formally list when not to use, but the use case is clear from the description.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds significant context: win-rate frame explained (P(price hit TP1 before SL, not realized PnL)), model internals never exposed, and forward-only Wilson-bounded metrics. This provides transparency 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, well-structured, and front-loaded. Every sentence provides distinct information without redundancy. It efficiently explains both modes and key caveats.

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, the description covers the essential behavioral context (two kinds, win-rate definition). It does not address performance or pagination but is sufficient for agent selection. Slight gap in not mentioning rate limits or error handling.

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%, providing baseline. The description adds value by explaining the meaning of each 'kind' (accuracy vs outcomes) and the behavior for empty/unknown kind (returns a menu). This enriches 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 that the tool retrieves realized track-record (proof of edge) grouped by kind, and distinguishes between 'accuracy' and 'outcomes' modes. However, it does not explicitly differentiate from sibling tools like 'calc_ev' or 'get_signals', which have overlapping purposes.

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 does not provide guidance on when to use this tool versus alternatives. It explains the two modes but lacks explicit context for selection among sibling tools, such as when to prefer 'get_accuracy' over 'calc_ev' or 'get_signals'. No exclusions or prerequisites are mentioned.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by noting that 'Market DATA, not advice' and that an empty bars list is normal behavior, which provides context beyond what annotations convey.

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

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

The description is three sentences plus a route hint, front-loading the core purpose. It is concise but could be slightly trimmed (e.g., 'Market DATA, not advice' is a bit tangential). Every sentence serves a purpose, but there's minor 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 presence of an output schema, the description does not need to detail return values. It covers the edge case of an empty bars list, mentions the API route, and provides usage context. It is nearly complete for a read-only data retrieval tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (symbol, tf, limit) with defaults and constraints. The description mentions symbol and timeframe in passing but does not add significant new 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 retrieves recent OHLCV candle bars for a symbol at a chosen timeframe, explicitly calling it 'the raw price/volume history other tools are derived from.' It distinguishes from siblings by stating its role as base data for other tools and lists specific use cases like inspecting trend, range, volatility, and volume profile.

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 raw price data and mentions feeding one's own indicators, but it lacks explicit guidance on when to use this tool versus alternatives like get_heatmap, get_market, or get_signals. No direct comparisons or exclusion criteria are provided.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable context: it's market data, not advice, and empty/unknown kind triggers a menu. This goes beyond what annotations provide.

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, well-organized paragraph. First sentence establishes purpose, then a bullet-like enumeration of kinds, followed by a disclaimer. 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?

With an output schema present and all parameters documented, the description covers all key aspects: kind enumeration, symbol requirements, empty/unknown behavior, and a disclaimeron the nature of the data. 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?

Both parameters are fully described in the schema (100% coverage). The description adds significant meaning by mapping each kind value to an endpoint and explaining the data it returns, greatly aiding parameter selection.

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 'Contextual market reads, grouped by kind' and enumerates each kind with a one-line explanation. It distinguishes itself from sibling tools like get_market or get_signals by focusing on multi-type context aggregation.

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 detailed guidance on which kind to use for what purpose, and explains the behavior for empty or unknown kind (returns a menu). However, it lacks explicit when-not-to-use or comparison with 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?

The description discloses behavioral traits beyond annotations: it notes the tool is real-time context (not advice), explains the behavior for empty/unknown kind (returns a menu), and warns that VPIN is a contested signal. Annotations already confirm read-only, idempotent, non-destructive nature, so the description adds complementary detail.

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 and front-loaded. It uses two sentences and a bullet-like listing of kinds with parenthetical clarifications. Every sentence adds value with no redundancy. The structure is efficient for an AI 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?

Given the tool has only two parameters with complete schema descriptions, a rich set of annotations, and an output schema, the description covers all necessary aspects: purpose, parameter variants, usage caveats, and behavioral notes. It is fully adequate for an agent to select and invoke this 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 has full coverage (100%) with descriptions for both parameters. The description adds extra meaning by elaborating on each kind's behavior (e.g., 'cvd' returns CVD series) and the menu behavior for empty/unknown kind, providing richer context than 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 clearly states the tool retrieves per-symbol order-flow microstructure grouped by kind. It explicitly lists the available kinds (vpin, cvd, sweeps, cross) and what each returns, and distinguishes itself from sibling tools like get_accuracy by noting VPIN is contested and should be paired with get_accuracy.

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: it returns real-time market context, not advice. It advises pairing VPIN with get_accuracy for edge verification. However, it does not explicitly state when not to use this tool or when alternatives like get_signals or get_whales might be more appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by explaining that the tool returns data (not advice) and that an empty matrix is a normal case. Does not contradict 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?

Extremely concise: two sentences plus a route note. No wasted words, front-loaded with purpose. Every sentence earns its place.

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

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

Given the tool has only one parameter, full schema coverage, and an output schema, the description is adequate. It explains the concept, normal empty case, and route. Could mention rate limits or pagination but not necessary for this simple tool.

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

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

Schema description coverage is 100% for the single parameter (symbol) with a clear example. The description does not add additional meaning beyond the schema, so 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?

Clearly states it provides a liquidation-heatmap matrix for a symbol, explains what it shows (price levels where leveraged positions cluster and may be force-liquidated), and its utility (anticipating acceleration or stalling). Distinguishes from sibling tools like get_candles or get_orderbook by being specific to heatmaps.

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

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

Provides context for use ('Anticipate where a move may accelerate or stall') and clarifies that it is market data, not advice. Notes that an empty matrix is normal. Lacks explicit mention of when not to use or alternative tools, but the context is sufficient for an agent to infer usage.

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 read-only, idempotent, and non-destructive. The description adds value by explaining the behavior of each kind (e.g., 'anomalies' includes volume_spike/phantom_tick with severity bands), the default kind, and what happens for empty/unknown kind. It also explicitly states 'Market DATA, NOT advice', disclosing the nature of the output.

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 efficient paragraph, front-loading the main purpose and then detailing kinds. Every sentence adds value. Could be slightly improved by using bullet points for the three kinds, but current structure is clear and not verbose.

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 an output schema present, the description does not need to detail return values. It covers all necessary context: what each kind returns, endpoints invoked implicitly, edge cases (unknown/empty kind), and usage intent (market context before drilling). The combo of annotations, schema, and description leaves 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?

Schema coverage is 100% with existing descriptions. The description goes beyond the schema by explaining the default behavior for kind (movers), the clamping and effective ranges for limit, and the case/space-insensitivity and scope (anomalies only) for symbol. This provides practical context for parameter usage.

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 is for whole-market reads grouped by kind, listing three distinct modes: movers, overview, anomalies. It specifies the action (get market board) and differentiates from sibling tools like get_candles or get_signals by emphasizing it's top-level context before drilling into specific 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?

Explicitly says 'find what's MOVING before drilling into one symbol', providing clear usage context. It notes when to use this tool (initial market context) and implies when not to (for detailed single-symbol analysis). Could be improved by listing alternative tools more directly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds details: cross-exchange aggregate, derived levels only, and that thin/uncovered symbols return null fields. 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 four sentences, front-loaded with the main functionality. It is concise but contains necessary technical details; minor redundancy could be trimmed but overall 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 the presence of an output schema, the description does not need to detail return values. It covers the tool's core function, edge cases (null fields), and the folding of S/R levels. It is complete enough for effective 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 coverage is 100% with good parameter descriptions. The description adds value by explaining the symbol parameter is case/space-insensitive and that include_sr defaults to true but can be set to false. It also mentions the default timeframe for sr_timeframe.

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 resource (symbol) and verb (get), and distinguishes from siblings by the unique combination of order-book data and S/R levels.

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 context: it's for order-book data with aggregated levels, notes thin symbols return null fields, and says 'market DATA, not advice'. It does not explicitly state when to avoid this tool or mention alternatives, but the context is sufficient for most use cases.

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 and destructiveHint false, indicating a safe read operation. The description adds valuable context: 'Tier-gated + moat-scrubbed server-side' and 'Market DATA, not advice,' which helps the agent understand access restrictions and legal disclaimers. 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 that efficiently covers purpose, quality variants, gating, and routing. It is concise but packs significant information; could benefit from slight restructuring but remains clear.

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 (5 optional params, output schema present), the description is comprehensive. It explains the two feed qualities, filtering options, pagination via cursor, server-side clamping, and legal disclaimer. The presence of an output schema means return values are covered elsewhere, so 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?

Schema description coverage is 100%, so parameters are already well documented. The description adds extra context beyond the schema, such as the routing differences ('normal→/v1/signals/pull, elite→/v1/signals/elite') and the nature of elite as 'lagged anti-front-run,' which aids in parameter selection.

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 pulls recent MidasFlow SignalEvent records, distinguishes between 'normal' and 'elite' qualities, and even gives the specific API routes. This sets it apart from sibling tools like get_flow 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 normal vs elite quality, noting that elite is premium+ and has lag. However, it does not explicitly compare with sibling tools or state when not to use this tool, though the context makes it fairly 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the agent knows it's safe and idempotent. The description adds behavior beyond annotations: raw notional is banded, it's market data not a signal, and behavior for empty kind. 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 dense paragraph that packs in all necessary information without unnecessary words. It could benefit from slight structuring (e.g., bullet points for each kind), but it is efficient and front-loaded with 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 four parameters with full schema coverage, an output schema (implied), and rich annotations, the description covers all necessary context: parameter constraints, behavior for empty/unknown values, the nature of the data (banded, not signal). There are no gaps in understanding how to use the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value: for kind, it explains the two options and their endpoints; for symbol, it notes case/space-insensitivity; for window, it gives the valid range; for exchange, it explains empty/all and error on unknown. This extra detail justifies 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 clearly states the tool's purpose: providing large-player or forced-flow intel grouped by kind. It distinguishes between 'whales' and 'liquidations' with specific endpoint references. The tool's role is distinct from siblings like get_signals and get_flow, which is reinforced by the statement that it is market data, not a signal or 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 provides explicit guidance on when to use each kind: for whales, a symbol is required; for liquidations, an empty symbol gives market-wide top movers. It also notes that empty/unknown kind returns a menu. However, it does not explicitly contrast with sibling tools like get_flow or get_market, though 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?

Annotations already indicate safe, read-only, idempotent behavior. The description adds further context: the result can be null for most symbols, includes a feed-safety check, and explains the folding mechanism. No contradictions 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 dense paragraph of four sentences. It is concise and front-loads the core purpose. While not structured with bullets, there is no wasted text; every sentence adds value.

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 (3 parameters, output schema, rich annotations, multiple siblings), the description covers the main points: what it returns, null handling, usage with calc_ev, routing, and the safety fold. It is complete enough for an agent to infer correct usage.

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 general context (null handling, use with calc_ev) but does not significantly enhance individual parameter semantics beyond what the schema already provides. The schema descriptions are already detailed.

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 (score) and resource (a calibrated P(TP1) band + trade plan + safety check for a symbol). It distinguishes from siblings like calc_ev (which consumes the band) and get_signals (different purpose). The title also reinforces the 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 explicitly tells when to use the tool (to get a score and plan) and how to use the output (feed into calc_ev). It warns against misinterpreting the band as a buy/sell signal and explains that null is valid. It does not compare with all sibling tools, 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.