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

Annotations cover the read-only/no-destruction profile, and the description adds substantive behavior beyond them: conditional output (ETF notionals only when all positions are in dollars; level ignored with weights), data freshness (end-of-day, refreshed after US close), and pricing ($0.015/position, $0.03 minimum). These are exactly the traits an agent cannot get from the structured fields.

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?

Front-loaded with the use case, then exclusions, then returns, then cost/freshness. Dense and mostly waste-free, though the returning-behavior sentence is somewhat long and could be split for scanability.

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?

No output schema exists, but the description explains return values, the conditional branch that gates ETF notionals, defaults (level default L3), limits (100 names), data latency, and cost. An agent has everything needed to call and interpret 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 coverage is 100% so baseline is 3, but the description adds meaning the schema does not: that 'level' is used only when every position is in dollars and is ignored when weights are supplied, and that the dollars-vs-weight choice gates which outputs appear. That conditional coupling of parameters to outputs is genuine added value.

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

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

States a specific resource (long-only portfolio hedge levels / ETF hedge notionals) and the exact conditions (up to 100 names, holdings-weighted L1-L3). It explicitly names the siblings it is not for, so an agent can distinguish it from riskmodels_portfolio_exposure and riskmodels_get_portfolio_risk_snapshot without opening schemas.

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?

Gives explicit when-to-use ('long-only book of up to 100 names'), when-not ('books with shorts or more than 100 names'), and names the alternative tool for each excluded case. Nothing is left to inference.

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 (readOnlyHint=true, destructiveHint=false), and the description goes well beyond them: the upstream endpoint (POST /batch/analyze), the exact return content (explained-risk shares and hedge ratios by layer, chart-ready), data freshness (end-of-day, refreshed after each US market close), and billing terms ($0.015 per ticker, $0.03 minimum). This is unusually rich behavioral 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?

Four tight sentences, front-loaded with usage and exclusions, then returns, then freshness and cost. Every sentence carries distinct information an agent needs; 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?

There is no output schema, so the description must carry return-value disclosure, and it does: risk-share and hedge-ratio outputs by layer with chart-ready framing. Combined with cost, freshness, and routing guidance, an agent has everything needed to call and interpret this 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?

With a single parameter at 100% schema description coverage, the schema already documents the ticker array including the 2-100 bounds. The description's '2-100 stocks' and ticker-symbol framing restate the schema rather than adding format, ordering, or validation nuance. 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?

States a specific operation (side-by-side comparison) on a specific resource (2-100 stocks across market, sector, subsector and residual risk layers). It explicitly names the siblings it is not (riskmodels_decompose for one stock, riskmodels_analyze_portfolio for a weighted portfolio), so an agent can select it 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 when-to-use condition (2-100 stocks side by side) and follows with two explicit when-not conditions paired with the correct alternative tools. Nothing about tool selection is left to inference.

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 cover safety (readOnlyHint=true, destructiveHint=false), yet the description adds substantial context beyond them: it discloses the POST /decompose endpoint despite being read-only, end-of-day freshness ('refreshed after each US market close'), and a concrete price of $0.005 per call. Cost and data-freshness disclosure go well beyond structured fields.

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?

Front-loaded with the use case, then exclusions, then return shape, freshness and pricing. Dense but every clause earns its place; slightly long, yet nothing is redundant with structured fields.

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?

No output schema exists, so the description carries the return-shape burden and does so clearly (explained-risk share, hedge ratio, hedge ETF, chart-ready data, one-line summary, hedge notionals when dollars is supplied). Combined with freshness, cost and endpoint disclosure, nothing material is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the semantic effect of the optional parameter ('with dollars it returns the ETF hedge notionals for that position at each level (hedge ratio times dollars)'), connecting an input to a concrete output beyond the schema's 'position size' wording.

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 the specific resource (one stock's risk split into market, sector, subsector and residual layers, plus ETF hedge legs for a dollar position) and explicitly distinguishes from siblings by name (riskmodels_compare for several stocks, riskmodels_analyze_portfolio for portfolios). An agent can identify the tool without opening the 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?

Unambiguous when/when-not: 'Use when you want one stock's risk...' followed by 'Not for several stocks (use riskmodels_compare) or a portfolio (use riskmodels_analyze_portfolio).' It even conditions the hedge-leg behavior on supplying dollars.

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 annotations (which already convey read-only, non-destructive, open-world), the description discloses the backing endpoint (POST /cohorts/pnl-decomposition), that selection+drift sum exactly to the total, that weights are held constant and not normalized, that shorts are negative weights, that unmapped positions appear in coverage.dropped, that data is historical end-of-day, and that each call costs $0.25.

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?

Dense but front-loaded: the usage condition and the primary exclusion come first, then the return/behavioral detail. Every clause carries information, though the mid-sentence semicolon chain is heavy; sizing is appropriate for a paid, non-trivial analytics call.

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?

There is no output schema, so the description must explain the return contract, and it does: selection, drift, their exact summation, and the coverage.dropped list. Together with the pricing and historical-data note, an agent has everything needed to call and interpret it.

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 reinforces weight-sign semantics ('a short is a negative weight') and adds the non-normalization/constant-weight constraint, but it repeats the schema's weight definition and adds little on level, end_date, min_names, or include_series.

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: attributing a book's realized residual return over a date window to stock selection versus drift. It clearly distinguishes itself from the general riskmodels_decompose and from riskmodels_portfolio_exposure by naming what it does not cover, so an agent can select it without opening schemas.

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 leads with explicit 'Use when...' guidance for the target scenario and provides an explicit exclusion plus alternative: 'Not for current risk or hedges (use riskmodels_portfolio_exposure)'. 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.

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

Annotations already declare readOnlyHint/destructiveHint=false, but the description goes well beyond them: it enumerates the returned metrics, clarifies that weights use end-of-day prices and holdings follow the latest filings, explains the 'common date' alignment, and discloses the $0.02 per call price. That is substantive behavioral context an agent cannot derive from 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?

Front-loaded with the use case and exclusion, then returns, then valid benchmark values, then price — a sensible information hierarchy. It is dense and long for a tool description, but each sentence carries concrete content, so little is wasted.

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?

There is no output schema, so the description takes on the burden of describing returns and does so (active share, RMS proxy, overlap, largest over/underweights). Combined with the enum breakdown and cost disclosure, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description exceeds it by decoding the benchmark enum (ff_own as the subject's own free-float-cap weights, the large/small style cells, and 'all' meaning every available benchmark) and by explaining the common-date alignment between subject and benchmark. It does not, however, explain the interaction of top with the subject/benchmark selection beyond what the schema states.

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 (compare) plus the exact resource (active share and largest active weights) for a named subject type (fund, 13F filer, ETF portfolio). It explicitly distinguishes itself from riskmodels_get_fund, riskmodels_get_filer and riskmodels_get_etf, so an agent can route 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 the triggering condition ('Use when you want to compare...with a benchmark') and supplies an explicit negative case with named alternatives ('Not for the subject's own holdings — use riskmodels_get_fund/filer/etf'). Both when-to-use and when-not-to-use are covered.

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 cover the safety profile (readOnly, non-destructive, open-world), yet the description goes well beyond: it discloses that ERM3 residuals are fitted without an intercept so residual_mean is non-zero, explains link_fit_resid_sd as a fit-quality measure rather than a standard error, states that subsector cohorts are unavailable, notes EOD refresh timing, and lists per-call pricing. This is exactly the extra context annotations cannot carry.

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?

Dense but front-loaded: routing guidance comes first, then return shape, then caveats and pricing. Every sentence carries information, though the residual-fitting and fit-quality caveats make it a long single block that could be slightly more scannable.

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

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

Although there is no output schema, the description enumerates the default return fields (residual_mean, residual_sd, mean_pairwise_corr, n_names, n_effective) and signals more are available, plus the endpoints, data-freshness cadence, and cost. An agent has everything needed to call and interpret the result.

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, but the description adds real semantic value: it maps series=true to the /cohorts/series endpoint versus /cohorts for one date, notes that the returned variable set is a default 'more on request', and introduces link_fit_resid_sd as a valid variable. These details go beyond the schema's per-field docs.

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+resource (cross-sectional residual statistics for SPY and the 11 GICS sector SPDR cohorts) and immediately scopes it against the two nearest siblings by name. An agent can distinguish it from get_peers and get_rankings 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 when' condition and follows with negative routing — 'Not for one stock's peers (use riskmodels_get_peers) or one stock's rank (use riskmodels_get_rankings)'. Both the trigger and the alternatives are named, leaving nothing to inference.

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 cover only the safety profile (readOnly/openWorld/non-destructive), and the description layers on traits they cannot express: the two backing endpoints, holdings sourced from the latest published file, registry freshness at end-of-day, and cost ('Free, no per-call charge'). Conditional output behavior is disclosed rather than left to inference.

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: scoping first, exclusions second, return shape and freshness third. The endpoint URLs are dense but add provenance value rather than padding.

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 no output schema, the description still declares the return envelope ({ snapshot, holdings }) and when each component appears. For a two-parameter read tool with full annotation coverage, nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by tying holdings_top to the presence of the holdings key in the response. It does not restate the 1-200 bound or case-insensitivity, which are already 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?

States a specific verb and resource ('one ETF's registry metadata and portfolio surface, optionally its largest holdings') and explicitly separates itself from sibling tools riskmodels_search and riskmodels_get_returns. An agent can pick it out of a 23-tool family 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?

Opens with an explicit when-to-use clause and adds two named exclusions with the correct alternatives for each case (ticker lookup -> riskmodels_search, daily returns -> riskmodels_get_returns). The conditional trigger for holdings (only when holdings_top is set) is also spelled out.

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 cover the safety profile (readOnlyHint, destructiveHint, openWorldHint), and the description adds genuinely new context: end-of-day cadence refreshed after each US market close, the underlying endpoints (GET /macro-factors vs GET /etf/factor-returns), and per-call pricing ($0.005 macro / $0.02 sector_etf). That is exactly the extra operational detail structured fields do not carry.

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?

Front-loads the use-when clause and the sibling exclusions before the per-mode detail. Dense but every sentence carries routing, semantics, or cost information; only the pricing-inline parentheticals are mildly verbose.

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

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

For a dual-mode read tool with no output schema, the description covers both modes' semantics, defaults, cadence, cost, and sibling disambiguation. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema carries parameter documentation (baseline 3). The description adds meaning by explaining that `kind` selects between two fundamentally different data shapes and return semantics (daily total returns over a range vs. one-date close + trailing 1/21/63/252-day returns), which goes beyond the raw enum 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?

States a specific verb+resource (returns macro factor series / SPY and 11 GICS sector SPDR trailing returns) and enumerates the factor keys (inflation, term spread, oil, gold, etc.). It explicitly distinguishes itself from the two closest siblings, riskmodels_get_macro_correlation and riskmodels_get_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?

Leads with 'Use when you need...' and adds 'Not for a stock's correlation with those factors (use riskmodels_get_macro_correlation) or one ETF's daily return series (use riskmodels_get_returns).' Both the positive trigger and the exclusion/alternative are named, so routing is unambiguous.

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, non-destructive, open-world, but the description goes well beyond them: it discloses the conditional behavior of holdings (only returned when holdings_top is set), the underlying endpoints and filing metadata (accession_number, filing_type, amendment_type), the null-before-vintage caveat, end-of-day pricing semantics, and explicit cost ($0.05, +$0.02 with holdings). This is rich, non-redundant behavioral 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?

Front-loads the trigger and exclusions, then the return shape and cost. It is dense and information-rich, with every clause carrying semantic weight, though the parenthetical enumeration of filing_type/amendment_type values makes it slightly heavier than strictly necessary.

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 no output schema, the description carries the full burden and delivers: it names the return object ({ snapshot, holdings }), the data each part contains, the conditional rule for holdings, the filing metadata, and pricing. Nothing an agent needs to call and interpret the result is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real meaning: it clarifies that holdings are returned only when holdings_top is set, and explains the source filing fields surfaced alongside them. It stops short of restating the 1-200 bound, but the conditional logic it adds exceeds what the schema conveys.

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: a 13F filer's profile, latest metrics, concentration, and optional largest holdings. It explicitly names what it is not for, distinguishing it from riskmodels_search and riskmodels_get_benchmark_fit, so an agent can route to it without opening sibling schemas.

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 when you want...' trigger and follows with two concrete exclusions pointing to the correct alternatives (riskmodels_search for the id, riskmodels_get_benchmark_fit for benchmark comparison). When-to-use and when-not-to-use are both fully spelled out.

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 declare readOnly/openWorld/non-destructive; the description adds substantial behavioral detail beyond them: the exact return shape { snapshot, holdings }, the backing endpoints, that holdings reflect the latest N-PORT filing while metrics use end-of-day prices, and the pricing model ($0.05, plus $0.02 with holdings). For a tool with no output schema, this is rich 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 front-loaded: usage and exclusions come first, then return structure, then cost. Every clause carries information (endpoints, refresh semantics, pricing), though the parenthetical endpoint detail is dense enough that a tighter phrasing could reduce length without losing meaning.

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 no output schema and a 2-parameter surface, the description still fully specifies what is returned (snapshot contents, holdings contents, their sources and ranking) plus freshness and cost. An agent has everything needed to call and interpret the result.

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 both parameters are already documented and the baseline is 3. The description goes beyond the schema by explaining the behavioral consequence of holdings_limit ('holdings, only when holdings_limit is set'), including that it triggers a separate endpoint and an extra $0.02 cost, which the schema does not convey.

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 (get) and resource (a US mutual fund's profile, return decomposition, hedge ratios, style-box ranks, and optionally holdings). It explicitly distinguishes itself from siblings by naming riskmodels_search and riskmodels_get_benchmark_fit as the tools for adjacent tasks, so an agent can route correctly 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?

Leads with 'Use when you want...' and then states two explicit exclusions with the alternative tools to use instead (finding the bw_fund_id, comparing with a benchmark). This is the when/when-not/alternatives pattern at full strength.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds useful context: it explains that reported versus imputed cost of debt/wacc use different sources, clarifies the as_of inclusion rule, states that only realized history is returned (no forecasts), notes that filings are picked up end-of-day, and gives a per-call price. However, it does not address key operational traits such as rate limits, authentication scope, or error behavior. With annotations carrying the safety profile, a 3 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?

The description is front-loaded with usage guidance and then systematically details outputs, caveats, and cost. It is dense and somewhat long, but with 9 parameters and no output schema, nearly every sentence earns its place by explaining what is returned or how the tool behaves. Minor redundancies with schema descriptions (as_of, grid) are the only waste.

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?

Without an output schema, the description carries the full burden of explaining return values, and it does so comprehensively—listing TTM ratios, leverage, betas, reported and imputed cost components, economic profit, equity-bridge decomposition, SEC line items, and grid behavior. It also covers caveats (realized only, no forecasts, end-of-day filings) and pricing, leaving the agent well equipped to call 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 description coverage is 100%, so the baseline is 3. The description repeats but does not meaningfully extend the schema's parameter documentation: its statements about as_of filtering and grid behavior restate what is already in the schema. It adds no new syntax, defaults, or constraints beyond the schema for any of the 9 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 states a specific verb and resource: 'point-in-time quarterly fundamentals or CAPM cost of capital for one stock'. It explicitly distinguishes itself from the sibling tool 'riskmodels_get_stock_snapshot' for risk/hedge numbers. An agent can identify the tool's unique scope without opening the 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?

The opening sentence specifies the exact condition for use ('when you need point-in-time quarterly fundamentals or CAPM cost of capital'), and the second sentence gives an explicit exclusion with the alternative tool to use instead. This covers when, when-not, and the alternative in a single compact routing statement.

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 cover the safety profile (readOnly, openWorld, non-destructive). The description adds meaningful behavior beyond them: the underlying endpoint (POST /correlation), default return basis (L3 residual), data freshness (end-of-day, refreshed after US close), and cost ($0.01 per call). Cost and latency signals are especially valuable and absent from structured fields.

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?

Front-loads the 'Use when' trigger, then the exclusion, then return/methodology, then freshness and price. Four sentences with no filler; each carries distinct, 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 no output schema, the description conveys what is returned (correlations over a trailing window, method and return basis) plus cost and freshness. It stops short of describing the response shape (e.g., per-factor mapping), which is a minor gap for a no-output-schema 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 method, ticker, factors, return_type, and window_days are already well documented. The description restates default behavior ('L3 residual return by default', 'Pearson or Spearman') which corroborates but does not extend the schema. 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?

States a specific purpose with verb-resource-scope: 'how one stock's returns co-move with macro factors such as rates, credit, oil, the dollar or volatility.' It explicitly names the sibling it is not (riskmodels_get_factor_returns), so an agent can select correctly without opening either 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 when' condition and follows with a clear exclusion ('Not for the macro factor return series themselves') plus the alternative tool to use instead. Both when-to-use and when-not are covered.

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 read-only/destructive, but the description adds substantive behavior: empty book when nothing is linked, sync timing ('as of the portal's last brokerage sync'), free/no REST charge, and that it does not place orders. These are useful traits beyond the structured fields.

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?

Front-loads the usage routing ahead of behavioral detail, which is the right ordering. The middle is dense but each clause (three book shapes, empty-book behavior) carries information not available elsewhere, so little is wasted.

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 no output schema, the description takes on the burden of explaining return values and does so fully: fields (ticker, quantity, market value, weight), has_shorts, and the three re-shaped book variants. An agent has everything needed to call and interpret it.

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?

Zero parameters, so the baseline is 4. The description confirms 'No inputs,' which closes any ambiguity about required arguments.

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 (returns) and resource (caller's linked brokerage positions), and explicitly distinguishes itself from riskmodels_analyze_portfolio and riskmodels_portfolio_exposure for conversation-typed books. The scope 'default riskmodels.net portfolio' is 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?

Gives an explicit when-to-use ('request concerns the caller's own linked brokerage book') and when-not ('Not for a book typed into the conversation'), naming the two alternative tools to route to. Nothing is left to inference.

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 cover the read-only, non-destructive, open-world safety profile, and the description goes well beyond them: result ordering (market cap), inclusion of each peer's market cap, end-of-day freshness ('refreshed after each US market close'), the source endpoint, and a per-call price. Cost and data-freshness context are exactly the traits annotations cannot convey.

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

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

Four tight sentences, front-loaded with the use condition and the sibling exclusion before the return and operational details. Each sentence contributes distinct information with no repetition of the schema.

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?

There is no output schema, yet the description specifies the return shape (peer list ordered by market cap with each peer's market cap), data currency, and pricing. For a simple three-parameter lookup, nothing an agent needs to select and call it correctly is missing.

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

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

Schema description coverage is 100%, with limit, ticker, and group_by all documented including an enum and defaults, so the schema carries the parameter burden. The description adds only an implicit echo of the group_by choice ('subsector ETF or sector ETF') and the market-cap ordering, which is the expected baseline when the schema is complete.

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 and resource ('the stocks that share a stock's subsector ETF or sector ETF') and explicitly separates this tool from riskmodels_get_cohorts. An agent can distinguish it from siblings like get_fund, get_etf, or get_cohorts 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?

It opens with an explicit use condition ('Use when you want...') and adds a negative routing rule ('Not for cohort-level residual statistics (use riskmodels_get_cohorts)'). The alternative and the condition that selects it are named directly.

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

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

Annotations only cover the read-only/non-destructive safety profile; the description adds substantial behavior beyond them: end-of-day data refreshed after each US market close, the backing endpoint (POST /snapshot), the exact decomposition levels and analytics returned, and a concrete price of $1.25 per call. The cost and data-freshness disclosures are exactly the kind of context annotations cannot supply.

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?

Five sentences, each earning its place: purpose, exclusions with alternatives, return contents, data cadence, price. Purpose and the routing constraint are front-loaded, and the dense return enumeration is necessary given there is no output schema.

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 no output schema, the description carries the burden of explaining what comes back and does so thoroughly (variance decomposition, hedge ratios, diversification analytics, attribution, drawdown, risk summary). Combined with cadence and pricing, an agent has everything needed to decide and call 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%, so the schema already documents benchmark, positions (with weight/dollars/shares alternatives) and lookback_days in detail. The description reinforces the long-only constraint but adds no syntax, format or default detail beyond the schema, so 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?

States a specific verb and resource (portfolio risk decomposition into market/sector/subsector/residual variance) with the scope constraint 'long-only' up front. It explicitly distinguishes itself from two named siblings (riskmodels_portfolio_exposure for long/short books, riskmodels_analyze_portfolio for ETF hedge notionals).

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 'Use when you want...' and follows with explicit NOT-for cases that route the agent to the correct alternative tool. Both the inclusion condition and the two exclusion conditions are spelled out, leaving nothing to inference.

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 readOnly/openWorld annotations, the description discloses the underlying endpoint, the returned fields (rank and percentile), data freshness (end-of-day, refreshed after each US market close), and cost ($0.005 per call). This is unusually rich operational context that annotations do not carry.

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?

Front-loaded with the use case and the sibling exclusion, then supporting detail. Four compact sentences, though the metric and window enumerations duplicate the schema and could be trimmed.

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?

No output schema exists, and the description names the returned values (rank and percentile) plus endpoint and freshness. Safety is covered by annotations, so nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including valid metric and window values. The description restates the same metric and window enumerations and only loosely clarifies that the cohort determines the comparison group; extension beyond the schema is minimal, so the 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?

States a specific verb and resource ('one stock's percentile rank within the universe, its sector or its subsector on a risk or return metric') and names the sibling it is not (riskmodels_screen_rankings). An agent can distinguish this from screening without opening the 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 when-to-use (single-stock rank/percentile) plus an explicit exclusion with a named alternative: 'Not for screening the whole universe (use riskmodels_screen_rankings)'. Routing is unambiguous.

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 read-only/non-destructive nature, but the description adds substantial context beyond them: routing (GET /lstar for one ticker vs POST /batch/lstar for 2-100), data freshness (EOD, refreshed after each US market close), and per-call pricing tiers.

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?

Front-loaded with the use-when and exclusions, then output shape, routing, threshold semantics, freshness, and price in a tight sequence. Despite being information-dense, every sentence (including pricing) earns its place for a cost-aware agent.

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?

No output schema exists, yet the description specifies what is returned per ticker (recommended depth by date, hedge ratios at that depth, daily residual return series). Combined with routing and data-freshness details, an agent has everything needed to call 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 coverage is 100%, so baseline is 3. The description adds real semantic value beyond the schema by explaining threshold behavior: omitted gives the depth ERM3 publishes, present gives the simplest depth whose marginal explained risk exceeds it.

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+resource (daily residual/stock-specific returns and recommended hedge depth) with clear scope (1-100 stocks). It explicitly differentiates from siblings by naming riskmodels_get_return_attribution for full factor splits and riskmodels_get_residual_signal for mean-reversion signals.

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

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

Opens with an explicit 'Use when' clause and immediately provides when-NOT guidance that routes to two named alternative tools with the distinguishing condition. An agent can select correctly without opening any 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: it is a basket-aggregated signal, not a forecast, based on end-of-day data refreshed after US market close, with a stated price per call. 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 front-loaded with the primary use case and exclusion, then adds return source, constraints, data freshness, and price. Every sentence earns its place 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?

There is no output schema, so the description should ideally explain return values more concretely. It does describe the conceptual return (basket-aggregated signal) and important caveats, but stops short of specifying response shape or field structure. Still, it is largely complete for an agent 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?

Schema description coverage is 100%, so the schema already documents tickers, weights, and signal_quality_min_quintile in detail. The description mentions optional weights and a minimum signal-quality quintile, but adds no syntax or format meaning beyond the schema, making the baseline 3 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 gives a specific verb-resource pair: aggregating the L3 residual mean-reversion signal over a basket of 1-100 stocks. It explicitly distinguishes itself from the sibling tool riskmodels_get_residual_returns, so an agent can route correctly without opening either 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?

It states when to use the tool ('Use when you want the L3 residual mean-reversion signal aggregated over a basket...') and when not to ('Not for the residual return series themselves (use riskmodels_get_residual_returns)'). This is explicit routing guidance with a named 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 cover read-only/safe semantics, but the description adds material context: returns are gross and in decimals, include_lstar adds a residual series at each day's recommended hedge depth, data is end-of-day refreshed after US close, and pricing is $0.04/call plus $0.01 per year beyond the first. It stops short of describing pagination, response size, or error behavior for an invalid ticker.

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 doing distinct work: purpose, exclusions, return shape, freshness and cost. The purpose is front-loaded and there is no redundant restatement of the name or 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?

With no output schema, the description carries the return-value burden and does: daily gross return plus additive components, decimal units, and the extra arrays gated by include_lstar. Freshness and per-call cost round out what an agent needs before invoking.

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 all five parameters are already documented, which sets the baseline at 3. The description only elaborates on include_lstar (hedge-depth residual series), adding marginal meaning over the schema's own 'adds the lstar level and lstar_residual_return arrays'; years, ticker, threshold, and market_factor_etf get no extra interpretation.

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 operation — one stock's daily return decomposed into market, sector, subsector factors plus a residual — and names the endpoint (GET /returns-decomposition). It distinguishes itself from the two closest siblings by name, so an agent can route 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?

Explicit when-to-use plus two explicit when-not-to-use cases with the correct alternative tool for each ('Not for raw total returns (use riskmodels_get_returns) or residual returns for many stocks (use riskmodels_get_residual_returns)'). Nothing is left to inference.

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 cover safety (readOnly, non-destructive, openWorld), and the description adds substantial behavior beyond them: return format (decimal, 0.01 = 1%), what each day includes (L3 market/sector/subsector hedge ratios and explained-risk shares), point-in-time history, end-of-day refresh cadence after US close, and a concrete price model ($0.02/call + $0.01/year beyond first).

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?

Five sentences, front-loaded with the usage condition and followed by exclusions, then payload details, cadence, and cost. Every sentence carries information, though the pricing and refresh sentences could be tightened slightly.

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?

No output schema exists, and the description compensates fully by describing the returned series format, its per-day contents, and the point-in-time/end-of-day semantics. An agent has everything needed to call and interpret the result.

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 both 'ticker' and 'years' (including the 1-15 bound). The description restates the 1-15 year range but adds no syntax or format detail beyond the schema, so the 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?

States a specific verb+resource+scope: 'daily dividend-adjusted total returns of one US stock or ETF over 1-15 years'. It also names the two siblings it is not (riskmodels_get_return_attribution, riskmodels_get_residual_returns), so an agent can disambiguate without opening schemas.

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 when' condition, then gives two explicit exclusions mapping each to the correct alternative tool. This is textbook when/when-not/alternatives routing.

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 (readOnlyHint, destructiveHint=false, openWorldHint), and the description adds material context beyond them: end-of-day freshness refreshed after each US market close, the underlying GET /metrics/{ticker} endpoint and that it returns the latest row including the hedge_levels block, and a per-call price of $0.005. Freshness and cost are exactly the operational traits annotations cannot express.

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 positive trigger before the negative routing, then return shape, then freshness and price. Every clause carries information an agent needs; nothing is padding.

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?

No output schema exists, so the description carries the return burden and does so — it names the endpoint, the returned row, and the hedge_levels block at L1/L2/L3. Combined with freshness and pricing, an agent has everything needed to call 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% and the single ticker parameter is fully documented there (case-insensitive, e.g. NVDA). The description only reinforces the 'one US stock' scope, which is already implied by the schema and the tool name, so the 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?

States a specific verb and resource ('one US stock's latest risk numbers') and enumerates the exact contents: hedge ratios to SPY/sector/subsector ETFs, explained-risk shares, volatility, price and market cap. It also names the sibling tools it is NOT for, so an agent can distinguish it 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 when you need...' trigger and then gives three concrete exclusions with the correct alternative for each: layer decomposition and dollar-position ETF hedge → riskmodels_decompose, multiple stocks → riskmodels_compare, daily history → riskmodels_get_returns. This is a complete routing rule set.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds behavior the annotations cannot: positions are netted by security and not rescaled, data is end-of-day refreshed after each US close, the response includes coverage gaps with reasons and warnings, and pricing is given ($0.25 up to 25 names, $1.00 above). This is exactly the beyond-annotation context the dimension rewards.

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?

Usage routing is front-loaded in the first two sentences, followed by returns, semantics, freshness, and price. Each sentence carries distinct information (routing, output shape, netting behavior, data cadence, cost), so nothing is wasted.

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?

There is no output schema, but the description enumerates the return payload (beta-dollars by sector, L1/L2/L3 ETF trades, systematic and residual dollar risk, coverage, warnings) and covers freshness, cost, and netting rules. Complete for an agent to call 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%, so all four parameters are documented in the schema itself; the description largely echoes the hedge_level default of lstar without adding new syntax. The only extra semantic, that positions are netted by security, is more behavioral than parameter-level. 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?

States a specific verb and resource ('returns beta-dollars by sector, the ETF trades that neutralise the book at L1, L2 and L3, systematic and residual dollar risk') and explicitly contrasts itself with the sibling riskmodels_analyze_portfolio. An agent can route between the two without opening either 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?

Gives an explicit trigger ('when a book has short positions or more than 100 names, or when you want its beta-dollars') and an explicit exclusion with a named alternative ('Not for long-only books of up to 100 names given as weights (use riskmodels_analyze_portfolio)'). When-to, when-not, and the substitute are all present.

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 safety (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lower. The description adds genuinely useful operational context beyond them: end-of-day data refreshed after each US market close, a $0.25 per-call price, and what gets returned (the ranked rows passing the filters). It stops short of describing pagination or auth, but adds real value over the structured fields.

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?

Front-loaded with the when-to-use clause, then the sibling exclusion, then return/freshness/cost details. Dense but every sentence carries information; there is no redundant repetition of the title or name.

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?

No output schema exists, so the description carries the return-value burden and does explain that it returns the ranked rows that pass the filters, plus freshness and pricing. For an eight-parameter screening tool this is largely complete, though row shape and pagination semantics remain implicit.

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 eight parameters, making the baseline 3. The description only conceptually groups the filters ('percentile, decile and sector filters') and cross-references the metric/cohort/window definitions used by riskmodels_get_rankings; it adds little syntax or format detail 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?

States a specific verb+resource: the names in the universe ranked highest or lowest on one metric with optional filters. It explicitly distinguishes itself from the sibling riskmodels_get_rankings ('Not for one stock's rank'), so an agent can tell them apart without opening either 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 when-to-use ('Use when you want the names in the universe that rank highest or lowest'), names the condition selecting the alternative sibling, and identifies the endpoint (POST /rankings/screen). No exclusions are left to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful extra context — the underlying endpoints per type, the end-of-day registry refresh (data freshness) and that the call is free (cost) — but says nothing about result pagination or output shape despite being a search/list 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?

Front-loaded with the use case and the exclusion before the endpoint detail, and every sentence carries routing, freshness, or cost information. It is dense — the endpoint URL enumeration is the most expendable part — but not padded.

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 9-parameter, zero-required, read-only search tool with full schema coverage and annotations covering safety, the description supplies the missing decision context (when/when-not, alternatives, freshness, cost). The remaining gap is how matches are returned/paged, which matters little given no output schema exists to describe.

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 every one of the 9 parameters is already documented in the schema, including defaults and the 'type X only' scoping. The description's per-endpoint field lists (e.g. fund returns bw_fund_id, ticker, style box) describe return content rather than parameter meaning, 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?

States a specific verb and resource — resolving a name/fragment to an identifier — and enumerates the identifier kinds (stock ticker, ETF ticker, bw_fund_id, bw_filer_id). It also names the sibling tools it is NOT (riskmodels_get_stock_snapshot, riskmodels_get_etf, riskmodels_get_fund, riskmodels_get_filer), so an agent can separate lookup from data retrieval 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?

Includes an explicit trigger ('use when you need to resolve a name or fragment to an identifier') and an explicit exclusion with the correct alternatives for the excluded case. Nothing about when to pick this tool versus the get_* siblings is left to inference.

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