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

No annotations exist, so the description fully bears the transparency burden. It details what the tool checks (concentration, correlation, volatility) and the optional candidate inclusion. However, it does not disclose rate limits, auth requirements, or any side effects, though none seem needed for a read-only analysis tool.

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

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

The description is well-structured with a brief intro, bulleted details, and clear Args/Returns sections. It front-loads the purpose and every sentence adds value without redundancy.

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

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

Given the output schema exists, the description doesn't need to explain return values but does anyway, showing thoroughness. It covers all parameters, usage hints, and return structure completely for the tool's complexity.

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

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

Schema coverage is 0%, but the description provides comprehensive parameter explanations, including examples for portfolio_json, valid values for period, default for corr_threshold, and format for candidates. This adds significant meaning beyond the bare schema.

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

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

The description clearly defines the tool's purpose: analyzing portfolio risk through concentration, correlation, and volatility checks. It also distinguishes from sibling tools by listing specific risk checks and optional candidate inclusion.

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 portfolio risk analysis before swaps but lacks explicit guidance on when to use this tool versus alternatives like compare_swaps or stress_test. No exclusions or when-not-to-use instructions are provided.

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

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

With no annotations, the description discloses the core behavior: pairwise comparison using composite scores and a threshold. It notes that scores_json is expected from score_tickers. It does not cover edge cases (e.g., missing tickers) or state side effects, but the main logic is transparent.

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 starts with a clear one-line summary, followed by a brief algorithm explanation, then a well-formatted Args list. Every sentence adds necessary 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?

The description covers the algorithm, parameter semantics, output format (JSON with recommendations and scorecard), and ties to the preceding score_tickers tool. With output schema present, return details are optional. Minor gaps: no mention of error handling or behavior when no swaps meet threshold.

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

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

Schema coverage is 0%, so the description fully compensates. The Args section explains the source of each parameter (scores_json from score_tickers), format (holdings/candidates as comma-separated), and default behavior (threshold default 15). This adds crucial meaning beyond the bare schema types.

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

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

The description states 'Generate pairwise swap recommendations from scored tickers,' which clearly identifies the verb (generate) and resource (swap recommendations). It distinguishes from siblings like score_tickers (which produces scores) and run_backtest (backtesting), making the purpose specific and non-overlapping.

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 explains when to use: after obtaining scores from score_tickers, to compare holdings vs candidates. It details the algorithm (threshold-based swap). However, it does not discuss when not to use it or mention alternative tools (e.g., analyze_risk for risk-only analysis), slightly limiting guidance.

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

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

With no annotations provided, the description carries full burden. It details the tool's behavior: matching trades into round-trips, computing swap alpha, benchmark-relative returns, and pattern analysis with recommendations. It does not mention side effects or permissions, but as a compute/analysis tool, this is sufficient.

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 brief intro, bulleted args, and returns. It is informative but slightly wordy, especially the trades example. Still, each sentence adds value and it is easy to parse.

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, no nested objects, output schema exists), the description covers input format, return structure, and provides an example. It is complete and leaves no major gaps for an AI agent.

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

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

Schema coverage is 0%, but the description provides rich semantics: explains trades_json format with an example, references prices_json from fetch_prices, and notes benchmark default. This fully compensates for the schema's lack of 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 analyzes trade attribution and rotation effectiveness, with specific details on matching trades into round-trips, computing swap alpha, and benchmark-relative returns. It distinguishes itself from siblings like compare_swaps or analyze_risk through its focus on attribution and recommendations.

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

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

The description explains input requirements (trades_json from trades, prices_json from fetch_prices) but does not explicitly state when to use this tool versus alternatives like compare_swaps. It implies usage for attribution analysis but lacks exclusions or scenarios where other tools are more appropriate.

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

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

With no annotations provided, the description carries full burden. It discloses that data is freely available from an external source, describes the return format, and notes decimal values. However, it does not explicitly state idempotency, latency, or any side effects, though the operation is clearly read-only.

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

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

The description is well-structured with a clear title line, context paragraph, and explicit Args/Returns sections. Every sentence adds value, and there is no fluff or repetition. It is appropriately sized for a single-parameter tool.

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

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

Given the tool has one optional parameter and a rich return format described in the description text, the description is largely complete. It provides source attribution and use case. The absence of a formal output schema in the provided definition is compensated by the textual description of return 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?

The only parameter, start_date, has a default value. The description adds meaning beyond the schema by explaining it filters dates on or after the specified date. This clarifies the parameter's purpose effectively.

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

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

The description clearly states 'Download Fama-French 5-factor + momentum daily data.' It specifies the exact resource (Fama-French factors) and action (download), and the context of factor decomposition differentiates it from sibling tools like fetch_prices or fetch_financials.

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 mentions 'Used for factor decomposition in stress testing' which implies a use case but does not explicitly state when to use this tool versus alternatives, nor does it provide any when-not-to-use guidance. The usage context is implied rather than explicit.

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

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

No annotations are provided, so the description carries the full burden. It mentions the API key requirement and return format, which is helpful, but it does not disclose potential errors, rate limits, or whether the operation is read-only. Behavioral transparency is adequate but not comprehensive.

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 an Args section and a Returns line. It is concise, each sentence adds value, and there is no fluff. Slightly more conciseness could be achieved, but it is already efficient.

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

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

Given the presence of an output schema, the description does not need to detail return values. It covers all parameters, the environment variable requirement, and the return type. However, it could be more complete by mentioning error handling or rate limits. Overall, it is sufficient 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 input schema has no descriptions, so the description fully compensates by explaining the format of 'tickers' (comma-separated), enumerating valid values for 'stmt_type' and 'period', and clarifying 'limit' as periods per ticker with a default. This adds substantial meaning beyond the schema.

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

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

The description clearly states the tool fetches financial statements (income, balance sheet, cashflow) from an API. The verb 'fetch' and resource 'financial statements' are specific, and the tool is distinct from siblings like fetch_prices which fetch price data.

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

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

The description specifies a required environment variable but does not explicitly state when to use this tool versus alternatives among the siblings. Usage is implied by the purpose, but there are no exclusion criteria or direct comparisons.

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

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

Discloses API with yfinance fallback, environment variable dependencies, and return format. No annotations provided, so description carries full burden; misses potential error scenarios.

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?

Well-structured, front-loaded with purpose, then API details, environment variables, parameters, and return format. Every sentence is informative and concise.

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

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

Comprehensive coverage: purpose, configuration, parameters, return format. Given an output schema exists, the description is sufficient 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?

With 0% schema description coverage, the description compensates fully by detailing each parameter's format, defaults, and source options, adding significant 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?

Clearly states it fetches historical daily OHLCV prices for given tickers. Distinguishes from sibling tools like fetch_financials and fetch_ff_factors.

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

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

Provides context on when to use the tool for historical price data, explains fallback behavior and environment variable configuration. Lacks explicit when-not-to-use but is otherwise clear.

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

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

No annotations, but description fully discloses behavior: read-only retrieval, return format, and effect of empty argument. No side effects or destructive actions.

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?

Well-structured with bullet points and sections. Every sentence adds value, no redundancy. Front-loaded with purpose and usage guidance.

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

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

Complete for a reference tool with multiple options. Explains input, output, usage context, and available skills. Output schema exists but description also clarifies return format.

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 has only 'name' with 0% description coverage. Description compensates fully by listing available skill values, explaining default behavior, and detailing what each skill contains.

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 verb+resource: 'Get domain knowledge for portfolio rotation analysis'. Differentiates from sibling tools (computational financial analysis tools) by being an informational/reference tool.

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

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

Explicit 'Call this BEFORE using other tools to understand how to interpret their outputs correctly'. Also explains how to list and retrieve skills.

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?

Given no annotations, the description discloses key behavioral traits: default momentum ranking, monthly rebalancing, trailing stops, transaction costs, and the interaction between ranking_mode and scores_json. It also notes that subsequent rebalances use momentum since scores aren't recomputed mid-backtest. While it doesn't explicitly state that the tool is read-only (non-destructive), the nature of a backtest implies no data mutation. This is adequate transparency.

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

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

The description is well-structured with a clear overview, bullet-listed parameters, and a return value section. Every sentence adds necessary information without redundancy. It is concise yet comprehensive, avoiding unnecessary prose.

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 all aspects needed for an agent: inputs (required and optional), behavior (momentum vs. score ranking, rebalancing), constraints (scores not recomputed mid-backtest), and outputs (metrics, equity curve, etc.). Despite no output schema, the return description is detailed. The tool is complex with 6 parameters, and the description leaves no gaps in understanding.

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 0% schema description coverage, the description fully compensates by explaining all six parameters in detail. It provides examples, defaults, and links to other tools (e.g., fetch_prices, score_tickers). This adds significant meaning beyond the schema, enabling correct parameter usage.

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

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

The description clearly states the tool's purpose: 'Backtest a rotation strategy on historical price data.' It distinguishes itself from sibling tools by focusing on rotation strategies, simulations with monthly rebalancing, trailing stops, and transaction costs. This specificity helps an agent select the correct tool for backtesting 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?

The description provides clear guidance on when to use the tool, including prerequisites (prices from fetch_prices) and optional inputs (strategy_json, scores_json, ranking_mode). It explains the default behavior and how different ranking modes affect the backtest. However, it does not explicitly mention when to use this tool over alternatives (e.g., stress_test vs. run_backtest), which would strengthen the guidelines.

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

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

Despite no annotations, description details the 6 stages and parameter behaviors (e.g., skip_refresh, source fallback). Discloses pipeline flow and data source selection. Lacks mention of potential side effects like API calls or caching, but overall sufficiently transparent for a complex tool.

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

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

Description is fairly long but well-structured with bullet points for stages and clear sections for args/returns. All content is relevant and adds value. Slightly verbose for a simple tool, but appropriate for the complexity of a 10-parameter pipeline.

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 10 parameters, 0% schema coverage, no annotations, but with an output schema (return mentioned), the description covers all parameters, pipeline stages, and return format. Provides sufficient context for an agent to understand input, behavior, and output.

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

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

Schema coverage is 0%, but description provides extensive parameter explanations with examples (portfolio_json format, candidates style, overrides_json structure, env var for source). Adds significant meaning beyond bare schema types and defaults, fully compensating for lack of 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?

Description clearly states 'Run the full 6-stage rotation analysis pipeline' with specific stages enumerated. Distinguishes from sibling tools (individual stages like analyze_risk, compare_swaps) by positioning itself as the main entry point for a complete 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?

States 'This is the main entry point for a complete rotation analysis,' implying use when full pipeline is needed. Does not explicitly mention when to use alternatives (individual stages) or exclusions, but context from sibling names makes this clear.

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

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

No annotations are provided, so the description bears full responsibility. It discloses that some scores are auto-calculated while others are manual via overrides, and describes the output format. It does not mention side effects or destructive actions, but it is safe and clear enough for an agent.

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-organized with a clear purpose statement, dimension list, parameter explanations, and return structure. It is somewhat lengthy but every part adds value; could be slightly more concise but remains effective.

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

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

Given the tool's complexity (7 parameters, output schema), the description covers purpose, dimensions, parameters, and output structure adequately. The existence of an output schema reduces the need to detail return values, but the description summarizes it well.

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 0%, but the description provides detailed explanations for each parameter, including defaults, examples (e.g., overrides_json format), and allowed values for style. This fully compensates for the lack of schema descriptions.

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

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

The description clearly states the tool scores tickers across 5 specific dimensions for rotation analysis. It uses a specific verb ('score') and resource ('tickers') with distinct dimensions, and differentiates from sibling tools like analyze_risk or fetch_prices.

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 rotation analysis but does not explicitly state when to use this tool versus alternatives, nor does it provide prerequisites or when-not-to-use guidance. It mentions parameters but lacks contextual usage advice.

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

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

No annotations provided, so the description carries full burden. It describes the computations performed but does not disclose any behavioral traits like side effects, safety, rate limits, or prerequisites beyond the parameter info. It is a compute-only tool, but the lack of explicit safety information is a gap.

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-organized with a purpose statement, bulleted list of test types, a clear 'Args' section for parameters, and a 'Returns' section. It is front-loaded and every sentence adds value without redundancy.

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

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

Given 9 parameters, 2 required, and the presence of an output schema, the description is fairly complete. It explains inputs (including derivation like 'from fetch_prices') and return format. Could be improved by explicitly stating that fetch_prices must be called first, but it is implied.

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

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

Schema coverage is 0%, so the description fully documents all 9 parameters. Each parameter has a clear explanation, example for portfolio_json, defaults, and types. This adds significant meaning beyond the schema, especially for required inputs.

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 comprehensive portfolio stress tests and lists specific test types (historical scenario replay, hypothetical shocks, Fama-French decomposition, Monte Carlo). This distinguishes it from sibling tools like analyze_risk (likely for single asset risk) and run_backtest (historical backtest).

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 running stress tests on a portfolio but does not explicitly state when to use vs alternatives or when not to use. However, the tool's purpose is clear and the context of sibling tools makes usage context understandable.

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