Redstone Markets

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint, openWorldHint), and the description adds substantial context beyond them: quarterly rebalancing assumption, the specific risk metrics computed (max drawdown, Sharpe, beta vs SPY, holdings correlation), benchmarking against SPY, and the 2–20 holding bound. An agent knows exactly what analysis is performed and under what assumptions.

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 triggering condition is front-loaded and the metric enumeration is dense but each item is informative rather than filler. The one long run-on sentence carrying the metric list is slightly heavy, but nothing is redundant or off-topic.

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?

An output schema exists, so return-value structure need not be spelled out, yet the description still names the headline metrics the agent should expect. Combined with the scoping rules, size bounds and examples, an agent has everything needed to invoke this correctly on the first attempt.

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 nested schema already documents ticker and weight semantics, so the description only needs to add marginal value. It does so with concrete format examples ('60% VTI, 40% BND', 'equal parts AAPL, MSFT, NVDA') that illustrate the weight convention, though the '2 to 20 holdings' constraint merely restates minItems/maxItems from 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 gives a specific verb (backtest) and resource (a weighted US stock/ETF portfolio) and enumerates the exact analytic outputs produced. It is immediately distinguishable from sibling tools like compare_securities, get_security_metrics and screen_securities, which operate on single securities or screens rather than a weighted 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?

It states clear triggering conditions ('when the user describes a portfolio ... with weights ... and wants to know how it would have done or how risky it is') and provides explicit exclusions ('Not for live brokerage accounts, trading or allocation advice'). It does not, however, name a sibling alternative for the excluded cases, so the routing guidance stops short of a full when/when-not/alternative triad.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: end-of-day rather than real-time data, the covered universe (US large/mid caps, major foreign stocks, US ETFs), and the concrete metric set returned. No auth or rate-limit detail, which is the only remaining 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?

Three tight sentences that front-load the trigger condition, then the return payload, then the data-scope caveat. Every clause carries information an agent needs (count range, metric list, chart horizons, data freshness, exclusions); nothing is 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 single-parameter, read-only comparison tool with an output schema, the description supplies everything the schema and annotations do not: when to reach for it, what it returns, how fresh the data is, and what universe it covers. No material gap remains for correct invocation.

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

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

Schema coverage is 100% for the single parameter, which already documents the ticker format (AAPL, VOO, BRK.B), the 2-5 min/maxItems bounds and ordering. The description's '2 to 5 US stocks or ETFs' restates the schema bounds and only adds the US-listing scope restriction, 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?

Names a specific verb (compare) and resource (2-5 US stocks or ETFs) and enumerates the exact outputs: returns, drawdown, Sharpe, beta, correlation and an overlaid 1Y/5Y chart. The scope limits ('End-of-day data', 'Not for intraday quotes') let an agent separate it from get_security_metrics and screen_securities without opening a schema.

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 trigger condition ('when the user wants to compare 2 to 5 ... side by side') with sample user phrasings, plus a clear exclusion ('Not for intraday quotes or recommendations on what to buy'). It does not name the sibling alternatives (get_security_metrics, screen_securities) for single-security or screening cases, so the routing guidance is clear but not fully closed.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context: end-of-day rather than intraday data, the coverage universe (US large/mid caps, major foreign stocks, US ETFs), and a chart output. It does not cover auth or rate limits, so 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 well-structured sentences: the usage condition is front-loaded, the metric list follows, and the scope exclusions close. Every clause earns its place with no repetition or filler.

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

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

An output schema exists, so return values need not be explained, and annotations already cover the safety profile. The description supplies the remaining needed context: when to use it, what metrics it returns, data timeliness, and excluded use cases. Nothing essential is missing for a single-ticker metrics 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?

There is one parameter with 100% schema description coverage. The schema already documents the ticker format and examples, and the description adds no further syntax or format detail. The baseline of 3 applies when the 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 states a specific verb+resource: retrieving performance and risk metrics for a single US stock or ETF. It lists the exact metric families (returns, drawdown, Sharpe, Sortino, beta, alpha) and scopes the coverage universe, which clearly distinguishes it from compare, screen, and backtest siblings.

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

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

It gives an explicit when-to-use condition ('when the user asks how a single US stock or ETF has performed or how risky it is') and clear when-not exclusions ('Not for intraday quotes, news, earnings, fundamentals or price targets'). It does not name sibling tools as alternatives, 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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuine behavioral context beyond that: universe size (~1,100 stocks, ~480 ETFs) and end-of-day cadence, which tells the agent not to expect intraday data. It stops short of describing pagination or rank-tie behavior, so 4 rather than 5.

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: the trigger condition and examples are front-loaded, the exclusion clause trails. No filler, every clause carries selection-relevant 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?

With an output schema present, return values need no explanation. The description supplies scope, universe, data cadence, and boundaries, which is everything an agent needs to decide to call this over its three 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?

Schema description coverage is 67%, so the schema documents most parameters including the metric enum and the risk-sorting hint. The description contributes sector/category examples through its sample queries but adds no syntax or unit detail beyond what the schema already provides, matching the 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?

States a specific verb and resource (ranked list of US stocks or ETFs by performance/risk metric) and immediately contrasts with siblings by ruling out fundamentals, news, and recommendations. An agent can distinguish this from compare_securities and get_security_metrics without opening any schema.

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?

Opens with an explicit 'Use this when...' condition plus three concrete example queries, and closes with an explicit 'Not for...' exclusion list. When-to-use and when-not-to-use are both spelled out.

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