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

Beyond the annotations (openWorldHint, destructiveHint), the description discloses critical behavioral traits: it populates historical data, auto-fetches metadata, takes a few seconds, auto-translates non-USD currencies and adds an FX pair, and returns a 409 for existing tickers. It also clarifies the currency exposure nuance to prevent user confusion. No contradiction with annotations; instead, it enriches them with concrete side effects and error conditions.

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 long but well-structured with bold headers for is_asset handling and currency handling. It front-loads the core action and purpose, then dives into necessary nuances. The enum lists are somewhat redundant with the schema but are presented coherently for the override case. It earns its length given the tool's complexity, though a slightly tighter delivery could improve conciseness.

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 (12 parameters, auto-detection logic, currency conversion, and side effects), the description is remarkably complete. It covers all key usage scenarios, edge cases (existing ticker, unsupported currency), and explains the return readiness. The presence of an output schema means return values need not be detailed, and the description properly focuses on behavioral and preconditions.

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?

With 100% schema coverage, the baseline is 3, but the description adds substantial semantic meaning beyond the schema. It explains how is_asset auto-detection works, when category/sector/asset_type become required, and lists the exact allowed enum values in a consolidated context. It also clarifies how units, display_name, and other fields are auto-detected, which the schema merely mentions. This is a paradigm of description adding value over 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's purpose with a specific verb and resource: 'Add a ticker to the feature catalog AND populate its historical data in one call.' It explains the outcome (feature ready for use) and distinguishes this from search_features by requiring a check for existing tickers. Although it doesn't explicitly compare to add_features_batch, the singular 'a ticker' and the detailed single-add workflow make the purpose unmistakable.

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 guidance: 'First use search_features to check if the ticker already exists' and warns about 409 errors for existing tickers. It also gives source selection advice ('yahoo' vs 'fred'). However, it does not explicitly mention the batch alternative (add_features_batch) for adding multiple tickers, so it stops short of fully distinguishing from all siblings.

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

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

Annotations include destructiveHint and openWorldHint, but the description adds significant behavioral context: parallel ingest with a 10-wide semaphore, the three-bucket return breakdown, the fact that 'already_existed' is not a failure, uniform versus auto-detected taxonomy behavior, and expected wall-time for typical batch sizes. It does not explain what 'destructive' means in this context, but the added detail exceeds annotation coverage.

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

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

The description is well-structured with a lead sentence, a bulleted return breakdown, a usage paragraph, a taxonomy note, and a performance estimate. Every sentence provides actionable information; no filler or redundancy. The format is scannable and front-loaded with the core 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?

For a tool with 7 parameters, an output schema, and annotations, the description is exceptionally complete. It explains return bucket semantics, addresses the single-add sibling, provides performance expectations, and clarifies parameter behavior in batch context. The presence of an output schema does not leave gaps because the description enriches its meaning.

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 per-parameter descriptions. The description adds valuable semantics beyond the schema: taxonomy fields 'apply uniformly to every ticker in the batch,' heterogeneous batches should leave them unset for auto-detection, and `source` is 'applied uniformly.' It also clarifies `is_asset` override behavior, complementing the schema's static 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 opens with a specific verb-resource pair: 'Batch-add multiple tickers to the catalog in one call.' It clearly distinguishes from the sibling `add_feature` by highlighting batch efficiency and from `create_portfolio` by noting the portfolio-bound alternative. The scope (multiple tickers, one call) is explicit.

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 guidance: 'Use this when you want to register a research universe in the catalog without committing to a portfolio' and contrasts with 'For portfolio-bound bulk imports prefer create_portfolio with auto_add=true.' It also advises when to leave taxonomy fields unset for heterogeneous batches, offering clear when-to-use vs. when-not-to-use guidance.

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

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

With readOnlyHint=true, the description adds substantial context: it computes at every timestep using Black-76, returns separate risk breakdowns, and shows how scenario analysis is chained. It discloses the computational scope and dependencies 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?

The description is front-loaded with the core purpose, then method, outputs, and usage prerequisites. It is longer than minimal, but every sentence adds operational detail for a complex tool; no filler or redundancy.

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

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

The description covers the tool's inputs (via flow job), computation, outputs, and a usage example. With an output schema present and 100% schema description coverage, it provides enough context for an agent to select and 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?

Schema coverage is 100%, so baseline is 3. The description adds value by specifying the source of flow_job_id (generate_flow_paths or simulate_flow_scenario) and giving a concrete scenario example, which clarifies how the parameters relate to a workflow. Other parameters are already well-described 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 opens with a specific verb+resource: 'Run options risk analysis on FLOW-generated paths for a mixed futures + options portfolio.' It details the Black-76 re-pricing, portfolio metrics, Greeks, and output breakdowns. It distinguishes from siblings like price_option and test_flow_risk by requiring a flow_job_id and positioning itself for portfolio-level analysis.

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: after obtaining a flow_job_id from generate_flow_paths or simulate_flow_scenario, and provides a scenario-analysis workflow. It does not name negative alternatives (e.g., 'use price_option for single-option pricing'), but the prerequisite and scenario usage are 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 indicate readOnlyHint and openWorldHint. The description adds meaningful behavioral context beyond these: it states the tool scans SEC filings and earnings calls, produces a 0-100 score, and handles both predefined and custom themes. There is no contradiction with the read-only annotation; the schema's mention of auto-creating a portfolio is not in the main description and does not factor here.

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 core function and output, the second gives the key invocation and theming options. It is tightly worded with no fluff, properly front-loaded, and every clause contributes useful 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 the tool has 6 parameters and an output schema, the description covers the essential selection criteria (which input to use, what themes to provide) without spelling out every optional parameter. The existence of an output schema partially removes the need to describe return values. Minor gaps include not explaining precedence if both portfolio_id and tickers are provided or defaulting of source_types, but these are adequately covered by the schema descriptions.

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 a baseline of 3 applies. The description adds value by clarifying the relationship between portfolio_id and tickers ('Pass either...') and by noting that themes can be predefined or custom, which is not explicit in the schema property description. This enriches the semantic understanding of the 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 begins with a specific verb ('Run qualitative (GRAIN) analysis') and states the resource (SEC filings and earnings calls) and the outcome (score company exposure to themes 0-100). This clearly distinguishes it from the sibling 'analyze_quantitative' and other analytical tools, making the 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 clear context for usage: it supports predefined or custom themes and mandates passing either portfolio_id or tickers. It does not explicitly name alternative tools for when not to use it, but the 'qualitative' vs 'quantitative' sibling distinction is obvious. The either/or guidance is a concrete usage rule.

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 side effects beyond the annotations (openWorldHint/destructiveHint): it 'creates models', auto-creates a portfolio when tickers are passed, and computes/returns beta-related artifacts. It explains behavioral nuances such as factor_last_date truncation, data_truncated_by, per-asset R² interpretation, and low R² implications. It also warns about degrees-of-freedom constraints and explicitly denies a regime-conditional API, which is valuable behavioral context. 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 lengthy and dense, but nearly every sentence earns its place by conveying critical limitations, parameter semantics, and interpretation guidance. It is front-loaded with the primary action, though the long paragraphs could be improved with bullet points or section breaks for scannability. It is not redundant, but it is at the upper limit of acceptable length.

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 is exceptionally complete given the tool's complexity. It explains the full pipeline, output fields, interpretation caveats (R², truncation), constraints (minimum rolling window, degrees of freedom), and the follow-up workflow (compute_returns with simulation_batch_id). It also covers when to avoid a use case (regime decomposition) and provides a substitute approach, making the tool fully contextualized among its siblings.

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?

With 100% schema coverage, the baseline is 3, but the description substantially enhances parameter meaning. It explains conditioning_set_id as 'market drivers', baseline_mode variants with real-time vs legacy FF5, rolling_window selection with statistical justification (e.g., 'rolling_window=90 supports up to ~9 RHS variables'), tickers auto-creating an equally weighted portfolio, and weights defaulting to equal weights. It adds practical semantics far 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 opens with 'Build and train linear factor models for a portfolio in one step (creates models → trains → computes betas)', which is a specific verb+resource statement. It further positions itself as 'the starting point for Moment (linear) analysis', clearly distinguishing it from siblings like compute_betas by emphasizing the one-step full-pipeline nature.

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 (starting point for Moment analysis), what is required (conditioning_set_id), and how to obtain it (from list_feature_set_templates or create_feature_set). It also gives clear exclusions and alternatives: 'there is NO regime-conditional... API' and instead advises re-running with a shorter rolling_window and comparing betas. It warns against rolling_window < 90 and directs the next step to compute_returns.

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 openWorldHint=true, so the safety profile is known. The description adds valuable context beyond annotations: warmup period behavior, transaction cost defaults, output structure (base vs combined vs per-rule attribution plus monthly returns, drawdown, turnover, cost analysis), and the contrast with simulated FLOW paths. This is substantive and non-redundant.

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 purpose, and each sentence earns its place: purpose + distinction, output summary, prerequisites, and alternative tool. No fluff or redundant 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?

Despite having an output schema (which relieves the description of explaining every return field), the description provides a useful high-level overview of the return structure and unique additions (monthly returns, drawdown, turnover, costs). It also covers prerequisites, defaults, and sibling differentiation, making it complete for a tool of this 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 parameters are individually described. The description adds meaning by explaining the warmup period ('pre-fills indicator state before the test period starts') and the default transaction cost (10bps), which clarifies the purpose of cost_bps and warmup_days beyond the schema descriptions. It also gives an example date format for start_date.

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 historical backtest of trading rules on real market data, explicitly contrasting with simulated FLOW paths. It specifies the verb (run a historical backtest) and resource (trading rules), and differentiates from forward_test_rules by mentioning the historical context and output differences.

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 prerequisites (create and activate rules via create_rule) and gives a clear alternative for forward-looking tests on synthetic paths ('use forward_test_rules instead'). This tells the agent exactly when to use this tool and when not to, with a named sibling.

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 key behaviors: it initiates a payment via Stripe Checkout, credits are added instantly after payment, and credits never expire. With only a destructiveHint annotation (which is vague), this adds meaningful context about the transaction flow and post-payment 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?

Four sentences, each earning its place: purpose, return value, pack options with pricing, and usage alternatives. Information is front-loaded and there is 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 simple one-parameter tool, the description covers all essential aspects: what it does, what it returns, available options, post-payment behavior, and related tools. With an output schema present and little ambiguity, this is 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?

The schema already fully describes pack_id with allowed values. The description adds direct value by mapping each pack ID to its credit amount and price, making it easier for an agent to choose the right pack without external lookups.

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 with a specific verb ('Purchase') and resource ('credit pack'), and specifies it returns a Stripe Checkout URL. This distinguishes it from siblings like list_credit_packs and get_credits.

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 provides when-to-use guidance: suggests using list_credit_packs for current pricing and get_credits to check balance first. This frames the tool within the broader workflow and distinguishes it from 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?

Beyond the readOnlyHint annotation, the description discloses critical behavioral details: the returned statuses ('running', 'completed', 'failed'), that it does not return results, typical duration expectations (training 5-15 min, etc.), and the instruction not to poll. This significantly enriches the agent's understanding of expected 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 succinct, front-loaded with the action and purpose, and each sentence delivers necessary information: status response, result exclusion, and usage guidelines. No filler or redundancy exists.

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 simple nature and the presence of an output schema, the description covers all necessary context: what the tool does, what it returns, when to call it, how often to call it, and where to go for results. The typical time estimates add practical context for user interaction.

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 documents both parameters with complete descriptions (100% coverage), including job_id's origin and job_type's allowed values. The tool description does not add substantial parameter-level detail beyond what the schema provides, so it meets the baseline expectation without innovating.

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 with a specific verb and resource: 'Check the status of an async Flow job'. It explicitly distinguishes from the sibling tool by stating 'Does NOT return results — when completed, call get_flow_results(job_id)', making its role unambiguous.

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

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

The description provides explicit usage guidance, including when to use it ('Check the status...'), when to use an alternative ('Does NOT return results — when completed, call get_flow_results(job_id)'), and a strong directive to avoid polling ('Call this ONCE, report status to the user, then STOP — do not poll in a loop'). This fully addresses usage context.

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 behavior beyond the readOnlyHint and openWorldHint annotations: it explains the probing mechanism, probability threshold bands, the meaning of the recommended generation methods, the cost (~1-15s), baseline reuse, and the auto_generate_baseline fallback. It also warns that feature_name must be the display name, not a ticker, which is critical. 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 long but every sentence carries actionable information. It front-loads the purpose and usage rule, uses a clear bulleted list for probability thresholds, and concludes with a critical data-format note. No filler or redundancy.

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

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

Given the tool's complexity (5 params, output schema, branching logic for method recommendation), the description is remarkably complete. It covers cost, baseline reuse, fallback behavior, low-probability workflow, and input validation, leaving no significant gaps for the agent to guess.

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?

Although schema descriptions cover all parameters (100%), the tool description adds semantic context by explaining how n_baseline affects resolution, what n_paths_target is used for (method recommendation), and when auto_generate_baseline creates a baseline. It also clarifies the constraints shape and requirement that 'lower' and/or 'upper' must be present, adding value over 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 a pre-flight feasibility check for constrained FLOW scenarios, explicitly stating it should be called before simulate_flow_scenario. It distinguishes itself from siblings by focusing on probability estimation and method recommendation, not simulation itself.

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

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

It provides explicit when-to-use guidance ('ALWAYS call this BEFORE simulate_flow_scenario when you have ≥2 constraints') and spells out the workflow for low-probability cases, including alternative actions like relaxing constraints or dropping least-essential constraints. It also names the sibling tool simulate_flow_scenario as the alternative.

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 (readOnlyHint=true, openWorldHint=true) already indicate a safe, non-destructive operation. The description adds valuable behavioral context by listing return fields (R², rolling_window, factor_last_date, data_truncated_by, simulation_batch_id) and explaining the meaning of data_truncated_by as stale factors. It doesn't address potential edge cases, but the annotations cover the most critical 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 moderately long but tightly packed with useful information. Each sentence contributes either usage guidance, return value semantics, or analytical tips. It's not overly verbose given the tool's complexity.

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 tool's context comprehensively: prerequisites (trained model_group_id), relationship to other tools (analyze_quantitative, compute_returns), key use cases, and interpretation of outputs. Has output schema present, so return values don't need full explanation, but important fields are highlighted.

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 parameters are already documented. The description adds extra meaning for lookback_days by suggesting example values (63, 126, 252) and explaining their analytical purpose (identifying regime changes). This exceeds the schema's basic type/description info.

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 'Compute factor exposures (betas) for an already-trained model group' with a specific verb and resource. It distinguishes itself by noting when it's needed vs. when it's not (analyze_quantitative already includes this step).

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 this tool: when you have a trained model_group_id and want to refresh betas with a different lookback window or get a new simulation_batch_id. It also tells you when NOT to use it (after analyze_quantitative).

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 openWorldHint=true. The description adds context beyond annotations by specifying the data source ('daily returns over a window'), input constraints ('2-20 tickers'), and return contents ('the matrix, per-asset annualized vol, and the top-correlated pairs'). This is meaningful but could be richer on edge cases or missing data handling; a 4 is appropriate.

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

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

Three sentences, every one earning its place. The purpose is front-loaded, followed by input constraints, output summary, and a comparative note. No fluff or repetition of annotations.

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 2 parameters, an output schema, and read-only annotations, the description fully covers what the tool does, its inputs, its outputs, and when to prefer it. Nothing essential is omitted, especially given the output schema supplies formal return details.

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 fully documents both parameters. The description repeats parameter constraints ('2-20 tickers', timeframe default '1Y') without adding new semantic meaning. It does mention the output concept, but that's not parameter semantics. Baseline 3 is correct.

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

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

The description states a specific verb+resource: 'Pairwise correlation matrix + annualized volatility from daily returns over a window.' It clearly distinguishes from siblings by noting it's 'Lighter than analyze_quantitative when you just want raw pairwise structure without a factor model,' and it also differs from compute_betas/compute_returns by explicitly covering correlation and volatility.

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 guidance is provided: 'Lighter than analyze_quantitative when you just want raw pairwise structure without a factor model' names an alternative and specifies the condition for choosing this tool. This directly tells when to use it instead of a heavier factor-model tool, satisfying the criterion for 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 declare readOnlyHint=true, and the description does not contradict this. It adds behavioral context beyond annotations by explaining that the server translates fractional changes to absolute levels automatically, that omitted factors default to no shock, and that users should include factor_last_values_raw in narration. These details are not evident from annotations alone, making the tool's execution behavior more predictable.

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 lengthy but every sentence contributes value: it covers purpose, prerequisites, examples, alternative tools, and output handling. The structure is clear with examples in bullet-like lines. A slight trim of the parenthetical phrase in the second example could improve conciseness, but overall it is appropriate for the tool's complexity.

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 params, nested objects, high schema coverage) and the presence of an output schema, the description covers all necessary context: how to obtain required inputs, how to format shocks, what to do with outputs (include factor_last_values_raw, check freshness warning), and when to use alternatives. It is self-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?

Although schema coverage is 100%, the description enriches parameter understanding significantly: it explains the fractional change convention with multiple concrete examples (e.g., 'TLT down 8.5%' → {'TLT': -0.085}), clarifies that the server handles conversion to absolute levels, and notes that omitted factors default to no shock. This goes far beyond the schema's raw 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's purpose: 'Run a what-if stress test on a Moment (linear) factor model.' It also identifies it as the 'PRIMARY tool for scenario analysis,' distinguishing it from siblings like simulate_flow_scenario, which is explicitly named as an alternative for Flow models.

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 context: requires simulation_batch_id from analyze_quantitative or compute_betas, explains the shocks format, and gives a direct alternative ('For Flow (generative) models, use simulate_flow_scenario instead'). It also tells the agent to check data_freshness_warning, which is a clear guideline for handling potential stale inputs.

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 useful behaviors beyond the annotation: auto-resolution of display_name, requirement for ticker/source, and return of a conditioning_set_id. However, the destructiveHint: true annotation is not addressed—the description's 'create' framing does not clarify any potential destructive side effects, leaving that behavioral aspect unexplained.

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 of high density: it states the purpose, the use case vs. alternatives, feature prerequisites, auto-behavior, and return value. No redundant or filler content, and the most important 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?

The description covers the intended downstream use, required inputs, auto-resolution behavior, and return value. With an output schema present, return format details are available elsewhere. The main gap is not reconciling the destructiveHint annotation, but overall the context is sufficient for a create tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by specifying that features must include 'ticker' and 'source' with YAHOO/FRED values, and that display_name is auto-resolved if omitted—details not fully captured in the schema's item 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 the tool creates a custom conditioning or target set from catalog features, with a specific downstream use for analyze_quantitative. It distinguishes this from pre-built templates, and the verb+resource construction is 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?

Explicitly advises using this tool for building arbitrary factor sets for analyze_quantitative instead of pre-built templates. It outlines required feature fields (ticker, source) and notes the auto-resolution of display_name, providing clear selection context. It does not mention exclusion cases, but the guidance 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?

Beyond the destructiveHint annotation, the description discloses server-side behavior: Yahoo Finance auto-ingestion, dropping missing tickers, import_summary counts, USD FX translation, and tier limits. It also explains operational consequences like truncation risk, giving the agent context that annotations alone cannot provide. 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 long but dense with purposeful information. It is front-loaded with the core purpose, then structured into clear sections: payload shapes, large-portfolio guidance, CSV-paste flows, size limits, and currency behavior. Every sentence earns its place, and bolding/scannable formatting improves readability.

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 complex tool with 8 parameters and a meaningful output schema, the description covers all essential operational context: payload shape selection, scale guidance, unknown-ticker handling, import summary reporting, size limits, and currency semantics. This is the full picture an agent needs 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?

Although the schema has 100% coverage, the description adds critical semantics: weights must sum to 1.0, equal_weight applies 1/N, the two payload shapes are mutually exclusive, and parallel arrays risk truncation for large portfolios. It also explains how auto_add and skip_missing interact, far exceeding the schema's basic field 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 opens with a specific verb and resource, 'Create a new portfolio from tickers', and immediately differentiates itself by explaining two payload shapes. This clearly distinguishes it from sibling tools like update_portfolio and delete_portfolio.

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 equal_weight=True for portfolios over ~50 assets, when to combine auto_add and skip_missing for CSV-paste flows, and explicitly tells the agent not to refuse large portfolios. It also names the alternative pattern to avoid and what not to warn users about, going well beyond basic 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?

No safety annotations are provided, so the description bears full responsibility. It discloses evaluation behavior, the difference between signal and binary rules, the mathematical scaling of signal weights, and critical failure mode: 'missing features cause rules to silently fail.' Also explains that evaluate_rules works with any feature in training_data. This is comprehensive behavioral disclosure.

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

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

The description is long but every section adds necessary value. It is front-loaded with purpose and evaluation context, then organized by rule type with examples, and finishes with a critical warning. Formatting with headings and code blocks makes it scannable. Despite length, it remains appropriately concise for the complexity.

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 nested object schemas and existing output schema, the description provides all necessary context: what the tool does, how rules are evaluated, both rule types, allowed values, examples, and warnings about data requirements. No critical information is missing for an agent to construct 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?

Although schema descriptions cover 100% of parameters, the description substantially enriches the schema by providing full rule syntax, example triggers/actions, lists of valid indicators and operators, and semantics for normalizer, max_weight, min_weight, and combinator logic. It also clarifies how priority should be used. This goes well beyond the schema 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 opens with 'Add a systematic trading rule to a portfolio' – a specific verb and resource. It distinguishes from siblings by explaining that rules are evaluated during forward_test_rules, not backtested, and details two rule types with distinct actions. This clearly separates create_rule from list/update/delete/toggle/validate/evaluate 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 states when rules are evaluated ('day-by-day on FLOW forward paths during forward_test_rules') and contrasts with live evaluation ('evaluate_rules'). Provides concrete guidance: 'Use signal rules (priority 0) for the core strategy; binary rules (priority 1+) for risk overrides.' Warns about missing features causing silent failure, giving users a clear decision framework.

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 include destructiveHint=true which aligns with the description's 'Save' action. The description adds substantial behavioral context beyond annotations: it clarifies the model_id relationship, specifies that each scenario is tied to one asset's model, and details the factor spec format and supported types ('fixed', 'percentile', 'shock'). This goes above and beyond the annotation's minimal safety hint.

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 a clear opening sentence, an immediate caveat ('does NOT run a simulation'), a critical model_id warning, and a compact factor format explanation. Every sentence contributes essential guidance without unnecessary 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 create operation with nested objects, an output schema, and sibling tools, the description covers all key aspects: purpose, alternatives, prerequisites, format details, and behavioral constraints. The explicit callout to list_model_groups and the factor type list ensure an agent can confidently invoke the tool. The presence of an output schema means return values need not be explained.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds crucial meaning for model_id ('individual per-asset model UUID from list_model_groups → models[].model_id, NOT the model_group_id') and factor_values (format and supported types). These additions are essential for correct parameter usage and significantly enhance 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 opens with a specific verb and resource: 'Save a named Moment scenario template for later reuse.' It clearly states the tool's function and distinguishes it from compute_returns ('This does NOT run a simulation'), making its purpose unambiguous and differentiated from siblings like simulate_flow_scenario and update_scenario.

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 and when not to use: '...use compute_returns with the factor values instead, or for ad-hoc tests' and implies use for reusable templates. It also provides a critical prerequisite (model_id from list_model_groups) and explains the distinction from model_group_id, giving clear decision 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 annotations already declare destructiveHint=true, and the description adds that deletion is 'Permanent, cannot be undone' and further restricts to non-shared templates. This provides meaningful behavioral context beyond the annotation without contradicting it.

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

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

The description is two short sentences, front-loaded with the primary action 'Delete a custom feature set' and followed by essential warnings. Every word serves a purpose, making it very 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 delete tool with one documented parameter and a destructive annotation, the description provides necessary caveats (permanence and shared template restriction). The presence of an output schema means return value details are not required, so the description is sufficiently 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?

The schema fully describes the sole parameter with 'UUID of the feature set to delete' (100% coverage). The description adds the context of custom feature sets but does not enhance the parameter's semantics 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 'Delete a custom feature set,' using a specific verb and resource. It distinguishes from sibling tools by specifying 'custom' and explicitly excluding shared templates, which sets it apart from template-related operations.

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 custom feature sets and notes the restriction 'Cannot delete shared templates,' but does not explicitly mention alternatives or provide when-to-use versus when-not-to-use guidance beyond this exclusion. This gives partial contextual 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 destructiveHint=true, and the description adds 'Permanent, cannot be undone,' which warns about irreversibility. It also specifies what is deleted (baseline or constrained scenario). 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?

A single sentence that efficiently conveys the action, scope, and consequence. No filler or repetition of the title.

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

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

For a simple delete tool with one parameter and an output schema, the description covers the essence: what action, what resource, and permanence. The parameter is documented in the schema, and the output schema exists, so no return-value explanation 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?

The schema fully describes the single parameter job_id with its origin (list_flow_baselines or list_flow_scenarios), so the description adds no additional parameter info. Baseline of 3 is appropriate given 100% 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?

Description uses specific verb 'Delete' and resource 'flow simulation job' with parenthetical clarification of types (baseline/constrained scenario). This distinguishes it from other delete tools and clearly states the action.

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 explicit guidance on when to use this versus other tools, nor does it mention alternatives or exclusions. However, the action and resource are clear, making the usage context implied. The parameter description references list_flow_baselines/list_flow_scenarios, which helps but isn't in the main 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 mark this as destructive, but the description adds critical context with 'Permanent, cannot be undone,' which goes beyond the structured metadata. This warning is essential for a delete operation and is clearly disclosed.

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 concise sentences, front-loaded with the action and resource, and contains no redundant information. Every word earns its place.

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

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

For a simple single-parameter delete operation with an output schema, the description is complete enough. It states the purpose, the ID parameter is documented, and the permanence warning is included. It does not cover error cases, but that is not essential given the low complexity and available annotations.

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 provides 100% coverage for the single parameter (analysis_id) with a clear description. The tool description adds minimal extra meaning ('by ID') but does not introduce new semantics beyond the schema, so baseline 3 applies.

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

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

The description clearly states the action ('Delete') and the specific resource ('saved GRAIN qualitative analysis') with the required identifier ('by ID'). This distinguishes it from sibling tools like list_grain_analyses, get_grain_analysis, and analyze_qualitative.

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 when to use the tool (when a saved analysis ID is available for deletion) and the permanence implies a decisive action. It does not explicitly mention alternatives, but the simple nature of delete makes this easily inferred from context.

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 goes beyond the destructiveHint annotation by explicitly stating that the operation cascades to models, simulations, and associated data, and that it is permanent and cannot be undone. This gives the agent critical context about the full impact of the operation.

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 short sentences and immediately communicates the action, scope, and irreversibility. Every word adds value, and there is no wasted information.

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

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

For a simple one-parameter destructive tool with an output schema and destructiveHint annotation, the description fully covers the key aspects: what is deleted, the cascading scope, and permanence. No additional context is needed for safe 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 schema already describes the only parameter (model_group_id) as 'UUID of the model group to delete', so schema description coverage is 100%. The description does not add additional parameter-level detail, giving the baseline score of 3.

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

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

The description clearly states the action ('Delete a model group') and specifies the resource and scope ('all its models, simulations, and associated data'). This distinguishes it from sibling delete tools like delete_portfolio or delete_scenario by naming the exact resource type and its contents.

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 context implies this tool is for permanently removing a model group, and the name matches the resource. However, there is no explicit statement of when to use this tool versus alternatives, nor any exclusions or prerequisites. The usage is implied by the resource type rather than stated.

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

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

The annotation destructiveHint: true already indicates a destructive operation. The description adds the valuable context 'Permanent, cannot be undone' which goes beyond the annotation by clarifying irreversibility. No contradiction exists between description and 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, consisting of two short sentences that front-load the action and key caveat. Every word earns its place with no unnecessary detail.

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

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

The tool has a single parameter, an output schema exists, and the description covers the operation and its permanence. Given the simplicity and the presence of structured metadata, the description is complete and sufficient for safe 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 fully documents the only parameter portfolio_id as 'The portfolio UUID to delete', achieving 100% coverage. The description's 'by ID' adds no additional meaning beyond what the schema already provides, 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 action ('Delete a portfolio by ID') with a specific verb and resource, and 'Permanent, cannot be undone' reinforces the nature of the operation. This distinguishes it from sibling tools like get_portfolio or update_portfolio.

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 use case is implied by the clear verb and resource, but no explicit guidance is provided about when to use this tool versus alternatives, nor are any exclusions or prerequisites mentioned. It does not name sibling tools for comparison.

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 provide no destructive hint, so the description carries the full burden. 'Permanently delete' explicitly discloses irreversibility, which is key for a mutation tool. However, it does not mention permissions, side effects, or what happens to dependent data, 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?

The description is a single sentence of nine words, front-loaded with the verb and resource. No filler or redundancy; every word contributes.

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 two-parameter delete tool with an output schema, the description covers the core action and permanence. However, it lacks usage guidelines and any notes about alternatives or side effects, making it adequate but not 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?

Schema description coverage is 100% with both parameters described as 'Rule UUID' and 'Portfolio UUID'. The description adds no extra meaning beyond tying the rule to a portfolio, 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?

The description clearly states the verb 'delete', the specific resource 'systematic trading rule', and the context 'from a portfolio'. This distinguishes it from siblings like toggle_rule (which likely enables/disables) and update_rule (which modifies).

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

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

No guidance is provided on when to use this tool compared to alternatives. Since siblings include toggle_rule and update_rule, the description could have mentioned that this is for permanent removal, while toggle_rule is for temporary deactivation, but no such context is given.

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 the behavioral detail that deletion is permanent and irreversible, which goes beyond the destructiveHint annotation. It does not mention side effects or permissions, but for a simple delete operation this is sufficient; a higher score would require more depth.

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

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

Two short sentences, front-loaded with the core action, and every word serves a purpose. The warning about permanence earns its place without bloat.

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?

A simple destructive operation with one well-documented parameter, a clear description, supportive annotations, and an output schema. The description fully covers behavior and consequences, making it complete for an agent to select and 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?

The input schema already provides full coverage with a clear description of scenario_id as 'The scenario UUID to delete' (100% coverage). The description adds no additional parameter semantics, so the baseline 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 uses a specific verb and resource ('Delete a saved scenario'), clearly distinguishing it from sibling tools like create_scenario, list_scenarios, and update_scenario. The purpose is unmistakable.

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 context is clear: use this tool to delete a saved scenario. The warning 'Permanent, cannot be undone' adds a cautionary usage guideline. However, it does not explicitly mention alternatives (e.g., update_scenario for modifications), so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint: true, so the safety profile is known. The description adds meaningful behavioral context beyond that: it returns raw path data with specific columns (path_idx, day, one per feature), is compatible with both baseline and scenario jobs, and provides a CSV output. This goes beyond the annotation's read-only flag without contradicting it.

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

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

The description is three sentences, front-loaded with the main purpose, and each sentence earns its place. The second sentence details the return format, and the third gives crucial source guidance. No redundant words or repeated schema information.

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

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

For a 1-parameter tool with an output schema and readOnly annotation, the description covers all necessary contexts: what it does, the exact output format, compatibility with baseline/scenario jobs, and where to obtain the required ID. Nothing important is missing for an agent to use it correctly.

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

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

The schema covers the only parameter (flow_job_id) with a description, so the baseline is 3. The tool description enriches this by expanding the list of valid source tools for the job ID to include list_flow_baselines/list_flow_scenarios, which is not present in the schema's parameter description. This is a useful addition for 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 starts with a specific verb 'Download' and clarifies the resource: 'all generated paths from a Flow generation job as CSV'. It explicitly names the output format and the data columns, and is clearly distinguishable from sibling tools like check_flow_job or get_flow_results by its focus on path download as CSV.

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 clearly explains when to use the tool (to download generated paths) and provides specific prerequisite guidance by listing where the flow_job_id comes from (generate_flow_paths, simulate_flow_scenario, list_flow_baselines/list_flow_scenarios). It stops short of explicit when-not-to-use instructions, but the context is strong enough for an agent to decide correctly.

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 several behavioral details beyond the readOnlyHint annotation, including the data source (training_data), refresh schedule (daily at 21:00 UTC), weekend/holiday behavior (uses most recent trading day), and the return values (per-rule triggered, action, indicator values, recommended_weights, weight_changes). It also notes that no FLOW model is needed. No contradiction with the read-only annotation.

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 well-structured, covering purpose, distinction, return values, data source, and usage in four tight paragraphs. Every sentence contributes actionable information 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 tool of this complexity, the description fully covers what it does, when to use it, what it returns, and its data freshness. The output schema already documents the return structure, so no further detail is needed. It also correctly positions this tool relative to forward_test_rules.

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 fully describes both parameters (portfolio_id as 'Portfolio UUID' and rule_ids with explicit instruction to omit for all active rules). The description adds no additional parameter-specific detail, so the baseline score of 3 is appropriate given 100% 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's function with a specific verb and resource: 'Check which portfolio trading rules trigger on TODAY's real market data.' It explicitly distinguishes itself from the sibling tool forward_test_rules by contrasting data sources, making the purpose unmistakable.

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 guidance: 'Use this for daily any rules fired? monitoring' and directs users to forward_test_rules for alternative use cases. It also explains the key difference from forward_test_rules in the first paragraph.

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 flag openWorldHint and destructiveHint, so the description need not repeat them. The description adds valuable context: the tool runs asynchronously, returns a job_id immediately, and takes ~3-5 minutes. This goes beyond the structured annotations, though it does not elaborate on the destructive hint.

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

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

Three sentences, front-loaded with the primary purpose, then essential workflow details. No redundant or filler content; 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?

The description covers the core purpose, the async behavior (including time estimate), the prerequisite, and the monitoring mechanism. An output schema exists, so return values need not be described. This is complete for a moderately complex 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%; all three parameters have descriptions in the schema. The tool description does not add additional parameter 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?

The description clearly states 'Validate a trained Flow model against real data' and lists specific evaluation metrics (Wasserstein distance, KS tests, coverage tests, marginal distribution checks). This distinguishes it from sibling tools like train_flow_model and generate_flow_paths.

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 provides a prerequisite ('Requires a trained Flow model (run train_flow_model first)') and names the follow-up tool to monitor progress ('Use check_flow_job(job_id=..., job_type='validate')'). This gives clear when-to-use 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 only include a title and no safety hints, so the description carries the burden. It discloses two output levels, the day-by-day processing approach, and a critical silent-failure caveat. However, it does not explicitly state whether the tool has side effects or mutates data, which would be useful given the lack of 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 bullet points, a numbered workflow, and separate sections for important caveats and prerequisites. It packs necessary information without fluff, and each sentence contributes to understanding the tool's behavior.

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, the description covers prerequisites, workflow, outputs, limitations, and alternatives. Since an output schema is present, not detailing return fields is acceptable. The description is thorough and leaves no significant gaps for an agent to select and 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?

Schema coverage is 100% for all three parameters, so the baseline is 3. The description adds meaningful context by explaining that flow_job_id must reference a completed FLOW job with paths for all referenced features, and it clarifies the default behavior when rule_ids is omitted. This goes beyond the schema's brief 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 uses a specific verb ('Forward-test') and a clear resource ('systematic trading rules against FLOW-generated price paths'). It also distinguishes itself from the sibling tool evaluate_rules by explicitly stating that evaluate_rules is for real market data, showing clear 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 explicit prerequisites (create rules, toggle active, generate FLOW paths), states what happens if rule_ids is omitted, and names the alternative tool for real-market testing. This gives clear when-to-use and when-not-to-use 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 include destructiveHint=true, and the description honestly notes that generation takes time but cached paths return instantly, adding value beyond annotations. It does not explicitly warn about cost, but the openWorldHint and destructiveHint are present in annotations; the description adds performance and caching context, which is useful. Minor gap: it doesn't state what happens if model_group_id is invalid or whether generation consumes credits, but with annotations present the bar is lower.

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: first sentence states purpose, second lists outputs, third gives prerequisite, fourth covers caching and performance, fifth gives defaults with context. Every sentence adds new information and the description is highly scannable, making it ideal for agent consumption.

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 an output schema, so return values are documented separately. The description covers prerequisites, performance, caching, defaults, and parameter semantics, making it complete for a complex generation tool. Slight deduction for not explicitly warning about credit/resource consumption, but given the output schema and annotations, the description is nearly 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the default horizon (60 ≈ 1 quarter) and n_paths (1000), and clarifies price_history_length's purpose ('warm up indicators like MACD or z-score before forward_test_rules'), which the schema's description only hints at. It also ties model_group_id to explicit source tools, enriching the parameter 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 starts with a specific verb ('Generate') and resource ('simulated multi-step price trajectories from a trained Flow model'), clearly stating what the tool produces: per-asset percentile bands, sample paths, and scalar terminal statistics. It distinguishes itself from siblings like simulate_flow_scenario and train_flow_model by naming the required model_group_id and referencing related 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?

The description explicitly states prerequisite: 'Requires model_group_id from train_flow_model or list_model_groups.' It also mentions caching behavior ('If paths already exist, returns cached results instantly') and gives performance context ('takes ~1-3 min on GPU'), which helps the agent decide when to call and what to expect. While it doesn't name alternatives for exclusion, the context is sufficiently explicit for correct tool selection.

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, covering safety. The description adds some behavioral context by stating the output is per holding and listing the exact classification dimensions, but it does not disclose additional traits such as data freshness, potential performance implications, or permission requirements beyond the basic read-only nature.

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, front-loaded sentence that immediately states the action and resource, followed by a concise list of the specific output fields. There is no redundant information or filler; every word 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?

The tool has only one required parameter (fully described in schema), an output schema is present (so return values need no separate explanation), and annotations cover the read-only safety profile. The description fully explains what the tool does, making it complete for the agent to select and invoke it correctly.

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

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

Schema description coverage is 100% (the portfolio_id parameter is documented as 'The portfolio UUID'), and the tool description adds no further meaning to the parameter. The baseline of 3 applies because the schema already adequately describes the only parameter.

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

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

The description uses a specific verb ('Get') and resource ('asset classification for a portfolio') while enumerating the distinct fields returned (sector, industry, country, exchange, asset type per holding). This makes it clear and distinguishes it from sibling tools like get_portfolio_value or get_portfolio_analytics.

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 when classification details per holding are needed, but it provides no explicit guidance on when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It is a simple definition without contextual placement 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?

Annotations already indicate readOnlyHint=true, so the baseline safety is known. The description adds behavioral context by clarifying the content scope (tier limits, overage rates, per-operation costs) and that it does not cover credit balance. This goes beyond annotations and prevents misuse, though it stops short of describing output structure or edge cases.

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 filler. The first sentence front-loads what is returned, and the second gives usage context and alternatives. Every clause earns its place.

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

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

For a zero-parameter read-only tool with an output schema present, the description fully covers purpose and usage context. It tells the agent exactly when to call it and clarifies what it does not do, making it complete for selection and 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 tool has zero parameters and the schema properties are empty, so the baseline is 4. The description correctly implies no parameters are needed; no additional parameter semantics are required.

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 subscription plan details including tier limits, overage rates, and per-operation costs. It uses a specific resource ('subscription plan') and immediate content list, and distinguishes from siblings by explicitly noting it is not for credit balance, which points to get_credits/whoami.

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 tells when to use: 'before running expensive operations' and provides exclusions and alternatives: 'not for credit balance — use whoami or get_credits'. This is direct when/when-not guidance with named 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 provide readOnlyHint=true, so the read-only nature is known. The description adds meaningful context about what the breakdown includes (per-operation counts, included limits, overage counts, costs) and the month format, which goes 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 concise, two sentences, with the action and resource front-loaded. Every sentence provides useful information without 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?

The tool has a single optional parameter, full schema coverage, a readOnlyHint, and an output schema. The description clearly covers what the tool does, what data it returns, and parameter format, making it complete for the given 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 schema already fully documents the 'month' parameter with format and default (100% coverage). The description repeats this information without adding new semantic details, so 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 a specific action and resource: 'Get detailed usage breakdown' for a billing month. It distinguishes itself from siblings like get_billing_info by focusing on detailed per-operation counts, limits, and costs.

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 clearly indicates when to use the tool: to get detailed usage for the current or a specific month, including the required month format. It provides context but does not explicitly mention alternatives or when not to use it, hence not a 5.

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

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

The annotation readOnlyHint: true already discloses that this is a read-only operation. The description adds value by specifying exactly what the full credit object contains (used, remaining, purchased packs, overage status), which gives the agent context about the response content. No contradictions exist.

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, front-loaded with the core purpose, and contains no filler. Every sentence earns its place: the first states what the tool returns, the second provides context for when to use it.

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 (0 parameters) and has an output schema, so the description does not need to explain return values. It fully covers when to use and what to expect, making it complete for an agent to select and 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?

With zero parameters, the schema fully covers the parameter semantics by defining an empty object. The baseline for 0 params is 4; the description adds no parameter-specific detail because none is needed.

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

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

The description clearly identifies the tool's purpose: retrieving credit balance details including used, remaining, purchased packs, and overage status. It distinguishes itself from the sibling tool 'whoami' by noting it provides the full credit object, making the scope 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?

Explicit usage guidance is provided: 'Use whoami for a quick summary; use this when you need the full credit object.' This names an alternative tool and states the condition for selecting this tool, satisfying the dimension fully.

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 the description does not contradict that. It adds meaningful behavioral detail beyond the annotation: results are sorted chronologically, filters include symbol/date range/horizon, and the return payload includes symbol, company name, report date, BMO/AMC time, and estimate/actual EPS. This is richer than simply restating the safety profile.

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 tight sentences: the first states what it does, the second details filter options and return fields, and the third gives the intended use case. No word is wasted, and each sentence earns its place.

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

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

With an output schema present and readOnlyHint annotation, the description still delivers sufficient context for correct invocation. It covers the purpose, all primary filter modes, expected return fields, and a practical use case. Everything an agent needs to select and call the tool is included or already available in structured 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?

Schema coverage is 100% and every parameter already has a description (e.g., 'Single ticker filter', 'End date YYYY-MM-DD (overrides horizon)'). The description restates these concepts but adds little new semantic value. The use of 'or' when listing filters could vaguely imply mutual exclusivity, though the schema's 'overrides' language partially clarifies precedence. Thus it stays at the baseline for well-covered schemas.

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: 'Upcoming earnings reports sorted chronologically.' It clearly identifies the tool's function and differentiates it from all sibling tools, as no other tool relates to earnings calendars. The listed filter and return-field details further reinforce 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 provides a clear use case: 'Use to flag earnings-event risk in a portfolio over the next N days.' This gives an agent the context for when to choose this tool, but it does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations only provide readOnlyHint, which is minimal. The description goes beyond by disclosing long-only constraints, the composition of each frontier point, and the historical vs. forward-looking distinction. This adds meaningful behavioral context, though edge cases (e.g., handling of missing data) are not covered.

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 the primary purpose. Every sentence adds value: purpose, output composition, and usage alternative. No redundant or vague 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?

Given the output schema exists, the description does not need to detail return values, but it still mentions key output elements. It covers what the tool does, constraints, and alternatives, which is sufficient for an agent to select and 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 describes all parameters with clear definitions, so schema coverage is 100%. The description adds general context about historical returns and long-only constraints but does not elaborate on individual parameter usage or formats. Baseline 3 is appropriate given the schema's completeness.

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 calculates the mean-variance efficient frontier for portfolio assets using historical returns. It distinguishes itself from siblings by explicitly noting it is historical analysis and pointing to optimize_portfolio for forward-looking scenarios.

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 provides when to use: historical analysis. Explicitly names the alternative for forward-looking optimization: optimize_portfolio with simulation data. Also mentions the long-only constraint as a boundary condition for 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 adds useful context beyond the readOnlyHint annotation by explicitly noting the result includes 'all features and their configuration.' This clarifies the scope of the returned data. No contradictions exist with annotations, and no extra safety warnings are needed given the read-only nature.

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-structured sentence that front-loads the action and includes the key scope ('including all features and their configuration'). No filler or redundancy.

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

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

This is a simple getter with one parameter, a read-only annotation, and an output schema. The description sufficiently covers what the tool does and what data is included (features and configuration). Given the output schema exists, not explaining return values is acceptable. The description is complete 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?

The schema covers 100% of parameters, and the parameter description ('UUID of the feature set') is clear. The description's mention of 'specific feature set' reinforces the need for an ID but does not add substantive meaning beyond the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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: 'Get detailed information about a specific feature set including all features and their configuration.' It uses a specific verb ('get') and resource ('feature set'), and distinguishes from siblings like list_feature_sets (which lists many) and search_features (which searches) by emphasizing 'specific' and 'detailed information'.

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

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

Usage is implied rather than explicit. The description indicates you use this when you need detailed info on a specific feature set, but it does not mention when to prefer alternatives (e.g., list_feature_sets for discovery, search_features for filtering). No when-not-to-use guidance is provided, though the simple getter nature makes the use case reasonably apparent.

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

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

Beyond the readOnlyHint annotation, the description discloses the specific return content per job type (terminal stats, percentile bands, sample paths, price_history) and behavioral traits such as the ~60% size reduction from summary_only. It also reveals preconditions (job completion) and scenario-specific fields, adding substantial context not present in 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 information-dense but well-organized by job type and usage scenarios. Every sentence conveys a distinct fact—alternatives, output composition, size optimization, and prerequisites. No fluff or redundancy; the length is justified by the tool's complexity.

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 output schema and readOnly annotation, the description covers all necessary aspects: return contents for all job types, usage of summary_only, alternative tools, and the prerequisite of checking job completion. It is complete without unnecessary enumeration of fields.

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 contextual meaning by explaining how job_type affects output (generate vs validate), the effect of summary_only, and the source of job_id. It also clarifies that sample paths are dropped with summary_only, enriching the parameter definitions.

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 results of a completed Flow job, with explicit breakdown for generation, scenario, and validation outputs. It distinguishes itself from siblings by naming check_flow_job (verify completion) and download_flow_paths (full raw CSV), so the agent knows exactly what this tool does.

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

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

Provides explicit usage guidance: 'Use check_flow_job first to verify the job is completed', 'Use download_flow_paths to get full raw path data as CSV', and explains when to set summary_only=true. It also clarifies which job types are supported and the default behavior.

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 and openWorldHint. The description adds useful context: data source (Alpha Vantage OVERVIEW), 24h cache with rationale, and 404 return for unsupported instrument types. This goes beyond the annotations but does not cover rate limits or response formatting.

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 verbose due to a long enumeration of fundamental metrics, which is likely redundant given the output schema exists. It could be condensed to metric categories plus source/caching/error details. The second sentence adds value, but the first sentence is overly detailed.

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 read-only tool with an output schema, the description covers the purpose, data source, caching behavior, and invalid-input error conditions. It does not mention rate limits or authentication, but these are not critical given the annotations and tool 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 input schema already describes the ticker parameter with an example (100% coverage). The description supplements this by clarifying that only US equities with SEC filings are valid and that ETFs/futures/crypto return 404, adding meaningful constraints on parameter 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 providing company fundamentals for a single US equity and enumerates specific metrics, making its purpose unambiguous. It distinguishes from sibling tools like get_quotes or get_history by focusing on fundamental data rather than price/volume.

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 fundamental analysis by listing metrics, but it does not explicitly state when to use this tool over alternatives. It provides constraints (US equities with SEC filings) and error behavior, but no clear 'use this instead of X' 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 mark readOnlyHint=true. Description adds that results are from 'completed' GRAIN analysis and lists included data types, giving context beyond the structured hint.

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, front-loaded with purpose, then a practical pointer. 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?

With output schema present and only one parameter, description covers purpose, content, and prerequisite. Sufficient 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 provides a clear description of analysis_id ('The analysis UUID from list_grain_analyses'); description reinforces this but adds no new semantic details, so baseline 3.

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

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

Clearly states it retrieves full results of a GRAIN analysis, enumerating content (theme scores, per-ticker breakdown, evidence passages). Differentiates from list_grain_analyses by referencing it as a prerequisite.

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 instructs to use list_grain_analyses first to find analysis_id, establishing a workflow sequence. No explicit exclusions but sufficient for a simple getter.

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 openWorldHint=true. The description adds valuable behavioral context beyond this: the downsampler keeps the last trading day of each period, large daily requests exceed the agent-side response clamp forcing a costly year-end-extraction pattern, and the frequency alias 'year_end'. This is actionable information the agent needs.

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 longer than average but every sentence carries important information: output definition, parameter alternatives, usage warning, downsampling behavior, and use-case context. It is well-structured with a clear progression, though it could be slightly tightened without losing 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?

For a tool with 5 parameters and an output schema, the description covers all necessary aspects: purpose, parameter semantics, behavioral quirks, cost implications, and use cases. Since an output schema exists, not detailing return values is acceptable. The description 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?

Schema coverage is 100%, but the description adds meaning beyond the schema: explains that start_date/end_date override range, lists the exact range options, clarifies the 'annual' alias 'year_end', and links frequency choice to response size and credits. This goes well beyond the baseline of simply having parameter 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?

States exactly what the tool returns: 'OHLC bars for a single ticker.' This clearly distinguishes it from siblings like get_quotes (current quotes), compute_returns (derived metrics), and get_fundamentals (fundamental data). The scope is explicit: single ticker, historical bars.

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: 'Use for ad-hoc time-series analysis the trained models don't already cover.' It also gives specific best practices, e.g., use coarser frequencies for multi-year analysis to avoid exceeding the agent-side response clamp and incurring extra credits/time. This helps the agent choose this tool over 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?

readOnlyHint=true already declares the read-only safety profile. The description adds meaningful behavioral context with 'sourced from ETF proxies', revealing data provenance and potential tracking differences from actual index levels. It also lists the exact return fields (symbol, name, price, change, change_pct), enhancing transparency beyond the annotation.

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 are front-loaded with the resource name, list the return fields, and include the data-source caveat. Every word earns its place 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 a simple tool with no parameters, a readOnlyHint annotation, and a full output schema, the description fully covers what the tool does, which indices it covers, how data is sourced, and when to use it. No meaningful 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?

The tool has zero parameters, so the baseline is 4 per the rubric. No parameter documentation is needed; the description focuses on output and use case.

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?

Clear specific verb 'snapshot' with explicit resources (S&P 500, Nasdaq 100, Dow, Russell 2000). The description inherently differentiates from sibling tools like get_quotes by scoping to a fixed set of major indices, making its purpose unmistakable.

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

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

The phrase 'Quick orient before deeper analysis' explicitly communicates the intended use case: a fast overview before diving into more detailed tools. It does not name alternative tools or exclusions, but the 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?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds rich behavioral context beyond these hints: specifying the data source (Alpha Vantage NEWS_SENTIMENT), detailing output fields (headlines, source, summary, sentiment label/score), and highlighting the nuance of per-ticker sentiment within multi-ticker articles. 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 tightly structured: it opens with the core purpose, then covers filters, output content, ideal use cases, and a sibling pairing suggestion. Every sentence serves a distinct function, 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 read-only news feed tool with a full output schema and 100% parameter coverage, this description is complete. It tells the user what the tool does, when to use it, what it returns, and how it complements market_radar. There are no significant gaps in context.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the semantics of tickers ('per-name news + sentiment'), giving topic examples ('earnings', 'mergers_and_acquisitions'), and suggesting a practical usage pattern ('pass the portfolio's tickers'). This goes beyond the schema's basic filter 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 'News feed with per-ticker sentiment scores (Alpha Vantage NEWS_SENTIMENT)', identifying the tool as a news retrieval and sentiment analysis service. It distinguishes itself from siblings by explicitly mentioning sentiment scores and per-ticker breakdowns, and by naming complementary tools like market_radar.

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 use cases ('any news on X?', 'what's driving X today?', 'portfolio-wide news roll-up') and names an alternative/complement: 'Pair with market_radar for the full what's happening briefing.' This gives clear guidance on when to use this tool versus siblings.

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

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

Annotations already declare readOnlyHint=true, so the description's main behavioral addition is the optional filter and the return-field breakdown. This is useful context beyond the annotation, though it omits potential pagination or ordering behavior, which is acceptable for a simple history retrieval.

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 core purpose and return content, the second explains the optional filter. It is front-loaded, to-the-point, and contains no redundant 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 the tool's simplicity (2 parameters, read-only, output schema present), the description fully covers what the tool does, what it returns, and how to narrow results. No critical contextual information is missing for a retrieval tool of this type.

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 both portfolio_id and simulation_batch_id already described in the input schema. The description adds a slight semantic link (simulation_batch_id to 'beta computation') but does not significantly enhance the schema's parameter 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 uses the specific verb 'Retrieve' with the resource 'past portfolio optimization results', clearly distinguishing it from siblings like optimize_portfolio and get_efficient_frontier. It also enumerates the exact contents of each entry, leaving no ambiguity about what the tool returns.

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 context: it retrieves historical optimization results, and the optional simulation_batch_id filter provides guidance for narrowing results. It does not explicitly state when to use it over alternatives, but the read-only nature and reference to 'past results' make the context 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 include readOnlyHint=true, so the safety profile is already disclosed. The description adds the return content (assets, weights, feature sets) but does not provide further behavioral context such as pagination, error handling, or permissions. It does not contradict 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 concise: two sentences that clearly state the tool's purpose and the parameter source. No unnecessary words or redundancy; 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?

For a simple get-by-ID tool with one parameter and an output schema, the description adequately covers the key contextual need: what the tool returns and where to find the ID. It does not elaborate on edge cases or distinguish among many sibling tools, but given the output schema and annotation, the description is largely complete. A bit more differentiation would push it to 5.

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

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

The input schema already describes portfolio_id as 'The portfolio UUID' (100% coverage). The description adds semantic value by indicating the ID comes from list_portfolios and that it refers to a 'specific portfolio', helping the agent understand the parameter's provenance and scope beyond 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 the tool's function: retrieving detailed information about a specific portfolio, mentioning the included content (assets, weights, feature sets). It distinguishes from list_portfolios by targeting a single portfolio, but does not explicitly differentiate from sibling tools like get_portfolio_value or get_portfolio_analytics, which may overlap in 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 usage when a specific portfolio's details are needed and provides a prerequisite ('Use the portfolio ID from list_portfolios'). However, it offers no guidance on when to prefer this over alternative portfolio-related tools (e.g., get_portfolio_value, get_portfolio_fact_sheet) and does not state 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?

Annotations declare readOnlyHint=true, and the description adds meaningful behavioral context: the backward-looking nature and the dependency on compute_betas. It also explains what the optional model_group_id does (factor attribution with examples). These details go beyond the annotation, though it doesn't describe error behavior or rate limits, which are not critical here.

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 main purpose and keeps information compact. Each of the four sentences adds a distinct point: metrics/timeframes, backward-looking distinction, optional feature, and prerequisite. The 'NEW:' prefix adds slight noise but overall it is well-structured and not bloated.

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 moderate complexity (four parameters, optional feature, prerequisites), the description covers the main use, timeframes, alternatives, and dependency. An output schema exists, so return-value details are not the description's responsibility. It even provides enough context to distinguish from many portfolio-related siblings, making it highly 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?

Schema description coverage is 100%, so baseline is 3. The description adds a concrete example of what model_group_id returns (factors like VIX, rates, oil) but does not clarify the 'rollup' parameter beyond the schema's terse 'Attribution period'. Overall the description adds minimal value over 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 opens with 'Get historical portfolio analytics' and enumerates specific metrics (Sharpe ratio, volatility, expected return, max drawdown, market beta) benchmarked against SPY. It clearly differentiates from sibling analytics tools by naming compute_returns and test_flow_risk as forward-looking alternatives, and the scope (historical, benchmarked) is precise.

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 ('backward-looking') and names alternatives ('for forward-looking risk, use compute_returns or test_flow_risk'). Also provides a prerequisite ('Requires compute_betas to have been run first via analyze_quantitative'), giving clear context on when this tool is applicable.

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

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

Beyond the readOnlyHint annotation, the description discloses the full set of return fields, the default benchmark behavior, the ability to override, and performance/cost characteristics. It sets clear expectations about what the tool does and its limitations 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?

The description is well-structured with a front-loaded summary, a bulleted list of return fields, and a short usage paragraph. Every sentence adds value, and the formatting makes it easy to scan.

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 is complete for a read-only, well-schema'd tool. It covers purpose, usage triggers, output structure, default behavior, and performance. An output schema exists, so not explaining return values in prose is fine.

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

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

Schema description coverage is 100%, with both parameters fully described. The description reinforces the benchmark override but adds no new meaning beyond the schema. Baseline 3 is appropriate since the schema already carries the burden.

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: 'One-call printable portfolio summary' with a specific list of returned metrics. It distinguishes itself from sibling tools by emphasizing the single-call, summary nature, and the usage phrase 'a one-pager', 'portfolio summary' gives a concrete use case.

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 when the user asks for...' with clear examples, and provides context like 'Single call, ~1-2s, free' to guide when to choose this tool over potentially heavier alternatives. It doesn't name alternatives, but the guidance is specific and actionable.

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 declare readOnlyHint=true, so the read-only nature is already covered. The description adds that the value is 'live' and lists the breakdown, but does not disclose any additional behaviors such as data freshness, latency, or error conditions.

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, front-loaded sentence that directly states the tool's purpose and outputs, with no filler.

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

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

Given the simple one-parameter schema and presence of an output schema, the description adequately conveys the tool's function and return contents. It does not discuss edge cases or prerequisites, but these are not essential for a straightforward read-only getter.

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 fully documents portfolio_id as 'The portfolio UUID' (100% coverage). The description does not add further parameter details, earning the baseline score of 3.

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

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

The description clearly states the tool retrieves a portfolio's live value, enumerating total value, P&L, and per-position breakdown, distinguishing it from sibling tools like get_portfolio or get_portfolio_analytics.

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 real-time portfolio valuation but does not explicitly contrast with sibling tools like get_portfolio_fact_sheet or get_portfolio_analytics, so it provides only implied guidance.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses important behavioral details: batch limit of 100 tickers, return fields (price, change, change_pct), and how unresolved tickers are handled without failing the batch. This adds significant 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?

The description is three sentences, each earning its place: purpose, behavior/limit, and use cases. It is front-loaded with the main purpose 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 single-parameter tool with an output schema, the description is complete: it explains what is returned, error behavior, limits, and typical use cases. No significant information is missing for a quote snapshot 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 already thoroughly describes the tickers parameter (array, max 100, example). The description repeats the 100-ticker limit but adds no new parameter-specific semantics. With 100% schema coverage, the baseline of 3 applies.

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

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

The description clearly states a specific verb+resource: 'Live price snapshot for one or more tickers (Alpha Vantage).' It distinguishes from siblings like get_history (historical) and get_fundamentals by emphasizing 'current price' and 'right now.'

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 provided: "Use for 'what's X trading at right now?' or to seed a quick position-level P&L calc." However, it does not explicitly mention alternatives or when not to use it, though 'live' implies not for historical 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?

readOnlyHint annotation covers the safety profile, and the description adds interpretive context about what the matrix represents and how to interpret it. No side effects or hidden behaviors are relevant, but the added semantic detail is valuable beyond the annotation.

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, each earning its place: states the operation, explains the interpretation, and highlights an implication. Cleanly structured and front-loaded with the primary action.

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 (one parameter, output schema present, read-only annotation), the description fully covers purpose and interpretation. It doesn't specify prerequisites like model group existence, but that is a minor gap for such a focused 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 already provides 100% coverage with a clear description for model_group_id ('UUID of the model group'). The description adds no additional parameter-level meaning, so the baseline score applies.

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

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

The description clearly states the action (Get) and the specific resource (cross-asset residual correlation matrix for a model group). It distinguishes this from sibling tools like compute_correlations by emphasizing residual co-movement after factor exposures.

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 useful context on when the output is meaningful (high residual correlations suggest missing factors) but does not explicitly compare to alternatives or state when not to use it. Usage is implied rather than directly guided.

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 readOnlyHint is provided, and the description aligns with that. It adds the detail about 'factor specs' being included, which is a slight behavioral/return signal, but no other behavioral traits (e.g., error behavior, auth) are disclosed. 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, short sentence that is front-loaded with the primary action and resource. Every word adds value, with no filler or redundancy.

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