ETFIQ

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: default fund selection (cheapest, one per class, no fee ceiling), the answer's defaults.line, refusal semantics, the not_advice line on every response, and the fact that returns are hypothetical with no extrapolation. It also warns that suitability and buy/sell questions are out of scope, which is behavior an agent cannot get 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?

The purpose and the two forms are front-loaded, but the body is a dense run-on that re-enumerates the entire asset-class list already present in the weights schema and spends a long paragraph on return-versioning details that matter more to output interpretation than to tool selection. Valuable content, but not every sentence earns its place in a selection-oriented description.

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 covers the return fields (total/average annual/volatility/drawdown across windows), the common.sentence explanation of start date, the not_advice line, defaults.line, and the compare.arguments handoff. For a complex nested-schema tool with zero required parameters, an agent has everything needed to call it 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 67%, and the description compensates well: it maps natural-language weights to the exact asset-class ids, explains that international-stocks is broad market-cap-weighted only while themed variants require an explicit tilt request, and defines the band-to-stock-share ranges. It also states defaults for criterion and fee ceiling behavior (cheapest funds, no fee ceiling) beyond what the schema says.

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?

Opens with a specific verb and resource ('Builds a custom portfolio of US listed ETFs from construction choices') and states it also shows the rule applied. It distinguishes the two construction forms and explicitly names compare_to_benchmark as the sibling that consumes its output, so an agent can place it immediately.

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?

Extremely explicit about when to use the weights form versus the band form, including the exact conditions (weights must sum to 100; band sets weights by stock share). It names the two refusal kinds (weights-total, unknown-class), excludes person-related inputs with kind person, and explains how to hand off to compare_to_benchmark — no inference required.

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. The description adds genuine beyond-schema behavior: the default selection rule including tie-breaking, the >5pp next-nearest rule, refusal with kind unknown-benchmark plus list, and that it estimates nothing when unpublished. It does not cover output shape, but there is no output schema so some return-format detail is absent.

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 one enormous run-on block with nested colons and semicolons, front-loading is weak, and key facts like the 5pp rule are buried mid-passage. Every fact arguably earns its place, but the structure is hard to parse and would benefit from being broken into labeled segments.

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

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

For a tool with no output schema, nested object param, and dual input modes, the description is thorough: it covers default selection, override, refusal, and the window/difference structure returned in both modes. Minor gap: it does not describe the output shape for the ticker mode's risk/cost fields in detail.

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 real semantic value: it explains the default rule for omitting benchmark, clarifies benchmark's id-vs-name forms, and elaborates what the portfolio object is (build_portfolio's compare.arguments.portfolio). It goes beyond the schema's succinct parameter descriptions.

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

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

The description names a specific verb (compare/set beside) and both resource forms (allocation ETF or a built portfolio) against an ETFIQ benchmark, and it distinguishes ticker mode from portfolio mode. It is clear what the tool does, though the dense phrasing makes the core purpose have to be excavated from long sentences.

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

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

Explicitly states when the benchmark defaults, when a comparison 'also' is set (gap >5pp or tie), and when to pass a reader-named benchmark with the exact phrasing and id format. It also documents the failure paths (unknown-benchmark refused, no estimate when unpublished), which is exceptional routing guidance.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the description's job is to say what comes back — and it does: how the benchmark was set, the ETF it is priced through, and fund/benchmark returns plus the gap per window. With no output schema, this disclosure is genuinely load-bearing and mostly 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?

Only two sentences, so not bloated, but the first is a long run-on with an awkward aside ('as its page names it') and stacked clauses. The scoping exclusion is buried mid-sentence rather than front-loaded.

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

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

For a single-ticker read-only lookup with annotations covering safety and a description covering return contents, an agent has enough to call it correctly. The only gap is disambiguation from the other benchmark-related 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 coverage is 100% and the single ticker parameter is documented with an example (JEPI). The description adds no further parameter meaning beyond what the schema already provides, 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 operation on a specific resource: measuring one ETF against its own named benchmark index or its own holdings, explicitly excluding a category stand-in. An agent can distinguish it from category/peer comparison tools, though the phrasing ('measures one ETF against, as its page names it') is convoluted enough to slow parsing.

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

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

Explicitly scopes the tool to a single ETF and routes model-portfolio benchmarks elsewhere via list_benchmarks. It does not clarify how this differs from close siblings like get_benchmark or compare_to_benchmark, which is the main remaining ambiguity.

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), so the description's contribution is the interpretive framing: states are Supports/Mixed/Challenges/Not enough data and are explicitly 'never a call to buy, sell or hold', plus every answer carries a disclosure and per-seat source links. That is genuinely useful context beyond the structured fields, though pagination/return shape detail is absent.

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 paragraph is front-loaded with what the tool is, then layers in the state vocabulary, the disclaimer and the seat links. It is dense but every clause carries information; the only mild redundancy is restating the state names twice ('each with its state' and 'each criterion's state').

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 must sketch the return payload and does: per-seat state, measurable coverage, per-criterion states, an attached disclosure, and a link per seat. What remains unclear is the form of 'how much of the seat could be measured' (count, percentage, enum) and behavior for an invalid ticker.

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 a single required parameter with 100% schema description coverage ('One fund's ticker, such as JEPI'), so the schema carries the burden. The description only reinforces the single-fund scope ('reads one ETF') and adds no format, casing or lookup semantics. Baseline 3 is appropriate.

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

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

The description names a specific resource and verb-equivalent: 'how each seat of the IQ Investment Committee reads one ETF', enumerating the 11 philosophy seats plus the ETFIQ Skeptic and the per-seat state model. An agent can tell exactly what comes back. It does not, however, position itself against nearby siblings such as etf_scorecard, etf_promise or etfiq_sections, which also produce per-ETF judgements.

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

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

Usage is implied rather than stated — an agent infers 'call with a ticker when you want the committee's per-seat verdicts'. The one real cue is that each seat links its own page carrying the published source and thresholds, hinting at a follow-up call, but no sibling is named and no when-not condition is given.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the tool only returns what the published page contains, the scorecard is conditional ('where one is published'), and missing-page pairs produce an error rather than fabricated data.

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, but the first is a long comma-spliced enumeration that is hard to parse and front-loads an awkward relative clause instead of the action. The content is dense but the ordering puts page-structure detail ahead of the core operation.

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 so by listing the page's components, plus it discloses the refusal case and the conditional scorecard. Only the fallback path and parameter ordering are left underspecified, which are minor gaps for a two-param read tool.

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

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

Schema coverage is 100% and both parameters carry examples (SCHD, VYM), so the schema does the documentation work. The description adds only that the inputs are a fund pair; it does not say whether a/b order affects the returned title or verdicts, which is the one semantic gap an agent would care about.

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 makes clear this retrieves ETFIQ's published comparison page for a specific pair of funds, and enumerates the page components (title, lead sentence, verdicts, overlap share, FAQ, scorecard). That scope is distinguishable from siblings like etf_profile or etf_overlap, though the opening clause ('Two ETFs compared as ETFIQ's comparison page for the pair publishes them') is grammatically tangled and buries the verb.

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?

There is no explicit statement of when to use this versus etf_overlap (which also covers shared holdings) or etf_profile. The only routing signal is the refusal behavior — 'A pair with no comparison page is refused, with each fund's own page' — which hints at a fallback without naming the sibling tool to call instead.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds substantial context beyond annotations: computation method, default 1W window, through dates, fund counts, streak and N-PORT months, and weekly Monday-to-Friday report behavior.

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

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

The description is dense and front-loaded, with the core purpose stated first, then mode-specific behavior. It is long and the second sentence is heavy, but most detail earns its place because the schema has no parameter descriptions.

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 zero schema description coverage, the description does a strong job explaining both return modes, default window, filters, and caveats like through dates. The main gap is the undocumented limit parameter.

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 must carry parameter meaning. It explains ticker, window values and default, and the desk/category/issuer filters, but does not describe the limit parameter's effect.

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 resource and computation: ETF fund flows as published by ETFIQ, computed from daily shares outstanding change times NAV. It clearly distinguishes the with-ticker and without-ticker modes, so an agent can understand exactly what the tool returns.

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

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

It clearly explains when each mode applies: with ticker for one fund's multi-window flows, without ticker for rankings and the latest weekly report. It also names filter dimensions, though it does not explicitly compare this tool to sibling ETF tools or state exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that: results are split into equity holdings and debt holdings, each weight is the issuer-published figure, and each carries the filing date of that book — useful freshness context. No pagination or ordering-limits behavior is described, which keeps it below a 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?

Front-loaded with the core purpose, then use cases, then return shape — a sensible order. Slightly padded by restating the same idea as both prose and example questions, but every sentence still conveys scope or output 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 no output schema, the description must describe returns, and it does: fund list, issuer-published weight, filing date, plus a separate debt-holder section. The only real gap is the undocumented 'limit' parameter and any ordering/cap behavior.

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%, so the description must carry both parameters. It does well on 'company' ('takes a company name or its ticker') and adds a coverage stat (31,019 companies), but the 'limit' parameter is never mentioned in either the schema or the description, leaving half the surface undocumented.

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 — 'which US listed ETFs hold a given company, ranked by how much of each fund it is' — which is precise and immediately usable. It also pins the direction of the relationship ('X is a company rather than a fund'), which implicitly separates it from the reverse-lookup sibling etf_holdings.

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 concrete triggering questions ('which ETFs hold X', 'which fund holds the most X', 'how do I get exposure to X') and an explicit scope exclusion (company, not fund; also covers debt/bond holdings). It does not name the alternative sibling tools by name, so routing is by inference rather than explicit direction.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds genuinely new behavioral context about data staleness — an issuer file read today versus a filing from two months ago 'are not the same answer' — which an agent would not learn from structured fields. It stops short of describing row limits or weight normalization, and the staleness discussion centers on a parameter not present in the schema.

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?

Content is front-loaded: purpose first, then usage sequencing, then parameter notes, with no filler sentences. Some phrasing is loose ('how old that is,' 'are not the same answer') where a crisp statement of as-of semantics would be tighter.

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, no annotations gap, and only two parameters, the description conveys the conceptual return (holdings by weight plus data age), which is the key missing context. However, it omits ticker format, top_n defaults, result ordering, and references a non-existent lag_days parameter, leaving real gaps for a holdings tool whose freshness semantics matter.

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%, so the description carries the full burden, but it only glosses 'top_n limits the rows' with no default or maximum. The required `ticker` parameter is never explained (format, single-fund only), and the description discusses a `lag_days` parameter that does not exist in the input schema, which actively misleads an agent trying to control data age.

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 resource and scope: 'what a fund holds, by weight, and how old that is,' which tells an agent this returns constituent holdings with weights plus a data-age signal. It also names sibling relationships (etf_profile, etf_overlap), so it is distinguishable from other ETF tools. The 'Analyst:' prefix and the vague 'how old that is' phrasing keep it short of a clean 5.

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 explicit sequencing guidance: 'Use after etf_profile to read the book, or before etf_overlap to see what two funds share,' which names alternatives and the conditions that select them. There are no exclusions (e.g., when to prefer etf_holders or etf_compare instead), so it falls short of full when/when-not coverage.

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 (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds meaningful behavior beyond them: results come from a frozen dated archive, so values are stable and reproducible unlike the mutable 'today' tools. It does not address archive start dates, missing dates, or error behavior, keeping it short of a 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?

Front-loaded with the purpose, then usage conditions, then the format requirement. Three sentences carry little waste; the parenthetical 'today moves overnight' is slightly colorful but reinforces the stability rationale that justifies using this 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?

For a one-parameter read-only lookup with no output schema, the description conveys what the return represents ('the pieces written that night') and the temporal contract. It stops short of enumerating what fields a 'piece' contains or how an out-of-archive date behaves, which would be needed for a perfect score.

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% — the single parameter is an unformatted string — so the description must compensate, and it does by specifying the accepted format ('Takes YYYY-MM-DD'). It adds no timezone, range, or validity constraints, so it is not complete, but it closes the most important gap.

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 what ETFIQ published on a given date from a frozen archive. It also explicitly differentiates itself from every sibling by noting the other tools answer about 'today' while this one is historical, which lets an agent 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?

Gives two concrete triggers ('a question is about a past date' and 'when a number needs to stay true after it is quoted') and names the generalized alternative ('every other tool here answers about today and today moves overnight'). It also states a negative boundary — 'not an arbitrary per-fund number on an arbitrary day' — which prevents a plausible misuse.

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 disclose readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the count returned reflects the full matching set even when the list is capped, and the filter matches words in addresses, not exact strings.

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: the core function, the recommended workflow, and the key counting caveat. The description is front-loaded and contains 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?

The description covers the purpose, the filter behavior, the count/cap gotcha, and the workflow with siblings, which is sufficient for correct invocation. However, since there is no output schema, it does not describe what fields each returned page will contain, which an agent might need for subsequent steps.

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%, so the description carries the burden for parameter meaning. It explains 'section' and 'contains' implicitly, and 'limit' is only alluded to as capping the list. It does not explicitly name or describe the parameters, leaving some ambiguity around limit's exact behavior and units.

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

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

The description clearly identifies the tool as listing pages within a single section, with optional filtering by an address word. It also explicitly distinguishes itself from sibling tools by placing it in the workflow between etfiq_sections and etfiq_page, so an agent can tell what it is for.

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

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

The description provides explicit workflow guidance: use after etfiq_sections to find a page, then etfiq_page to read it. It names the relevant siblings, though it does not state conditions where this tool should NOT be used or which sibling might be preferable in specific cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that: it discloses the response shape (names the page, quotes the answering paragraphs, returns the page's text) and the no-topic behavior (returns the page list). It stops short of describing not-found or ambiguity handling.

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?

Purpose is front-loaded and the sentences are dense but each carries information (coverage, invocation, benchmark caveat, no-topic fallback). The long parenthetical listing desks and the embedded benchmark aside make the first sentence heavy, costing some readability, but there is 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?

With no output schema, the description carries the burden of explaining returns, and it does so concretely (page name, quoted paragraphs, full page text). Combined with the coverage list and the no-topic mode, an agent has enough to call it correctly; only failure/ambiguity behavior is left unaddressed.

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, so baseline is 3. The description adds meaning beyond the schema: it clarifies that topic should be free-form natural language ('the reader's question in their words') rather than a page identifier, and that omitting it switches the tool into a page-listing mode, which the schema does not state.

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?

Opens with a specific verb+resource: it retrieves the methodology page explaining how ETFIQ computes a figure, and enumerates the covered domains (flows, scores, categories, look-through, benchmarks). The scope is distinguishable from generic page tools, though it never names siblings like etfiq_page, find_page, or etfiq_list, so an agent must infer the boundary itself.

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

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

Gives explicit invocation guidance: 'Pass topic, the reader's question in their words' and 'Call with no topic for the list of pages', which covers both the primary and degenerate call patterns. It also adds a routing rule that a single fund's own benchmark follows its desk's rule and 'never the model-portfolio benchmarks', implicitly steering agents away from get_benchmark/list_benchmarks for that question, but no alternative tool is named.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered structurally. The description adds genuinely useful behavioral detail beyond that: it returns page *content*, not navigation chrome, which tells the agent what kind of payload to expect. It stops short of noting format details like truncation or handling of unpublished paths.

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, zero filler, with the core function and output shape front-loaded before the path-format detail. Every clause contributes either scope, differentiation, or input format.

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 one parameter, no output schema, and full annotation coverage, the description supplies what an agent needs: what it reads, what input shapes it accepts, and that it returns content rather than navigation. Minor gaps remain around response size/format and failure modes for unpublished pages.

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% and the single parameter is entirely undocumented in the schema, so the description carries the burden. It does so reasonably well by giving an example value (/themes/cyber) and stating a full URL is also accepted, though it does not specify error behavior for invalid or unpublished paths.

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 ("Read any published ETFIQ page as text") and enumerates the page classes it covers (theme hub, ranking, comparison, issuer, methodology, dated study). The clause about reaching all 40,000 pages that the typed tools do not cover explicitly differentiates it from siblings like etf_profile or etf_theme.

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 clear usage context: it is the catch-all reader for anything the typed tools miss, and it accepts either a path or a full etfiq.com URL. It does not explicitly compare against the sibling find_page, which is the closest alternative for locating content, so routing guidance is slightly incomplete.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is settled. The description adds that the result is a per-section listing with page counts and contents, but nothing about response shape or size beyond that. Adequate addition, not rich.

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 purpose well, but the long parenthetical enumerating fund flows, weekly report, model portfolios, prediction-market funds, issuers, methodology, rankings and screener is a run-on list that could be trimmed or bulleted. Every element is relevant, yet the structure is dense and clunky.

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

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

For a zero-parameter navigation tool with no output schema, the description is sufficient: it says what is indexed, that page counts are included, and when to reach for it. Only the precise return format is left unspecified, which is a minor gap at this complexity.

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

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

Zero parameters, so there is nothing for the description to document; the baseline for a param-free tool is 4. The description correctly implies the tool takes no input and returns a fixed catalog.

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 — ETFIQ's published sections with page counts — and enumerates the main pages it covers, so an agent knows it is the catalog/overview entry point. It is distinguishable from data siblings like etf_flows or etf_rankings, though the differentiation is implied rather than named.

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?

"Start here when the question is not about one fund" gives an explicit positive trigger and a clear exclusion (single-fund questions route to profile/holdings tools). It stops short of naming the alternative tool to use instead, but the routing condition 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, idempotent, non-destructive, so the bar is lower; the description still adds meaningful behavior: rows are dated with the days they cover, no single-day return exists so today's movers are flows, min_assets_usd exclusion applies only to the return lists, and leveraged funds are flagged. That is substantive beyond the annotation set, though it does not say how many lists come back or whether lists can be empty.

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 purpose, then scope, then filters, then next steps – a sensible order with no filler sentences. It is a dense, slightly run-on single paragraph, and the two window enumerations make it longer than strictly necessary, but each clause carries 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 no output schema, the description does the work of telling the agent it gets dated rows across flow and return lists with leveraged flags. The only real gap is that the exact return shape (number of lists per call) is only implied rather than stated.

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% and the description compensates fully for all six parameters: enumerates the flow_window values and its 1D default, the return_window values and its 1M default, the desk and category value sets that the bare string schema omits entirely, the min_assets_usd default of 100,000,000, and limit's 1–25 range with default 10.

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?

Opens with a specific framing ('what moved') and then names the exact resources: biggest fund inflows and outflows over a flow window plus best/worst total returns over a return window. The distinction from siblings like etf_flows and etf_rankings is implicit in the two-sided ranking-plus-flows framing, and the 'today's movers are the flows' note makes the intent unambiguous.

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

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

Explicitly positions itself as the entry point of a workflow ('Start a daily scan here, then etf_profile or etf_risk_check on a name that stands out'), which is real routing guidance to named alternatives. It does not, however, state when to prefer this over the sibling etf_flows tool, leaving one obvious overlap unresolved.

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), so the bar is lower, and the description still adds useful behavior: each event is a dated sentence carrying its SEC form, filing date, and link, with closures and launches ordered first. The note that 'matching is the whole count' clarifies that limit does not affect the reported total. Return format is described but pagination beyond limit is not addressed.

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?

Content is front-loaded — source, coverage, and event taxonomy come before parameter behavior. The middle sentences are dense and somewhat run-on (parenthetical definitions plus multiple filters in one clause), but no sentence 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?

For a read-only, four-parameter, no-output-schema tool, the description covers source, event taxonomy, defaults, filtering, ordering, response shape, and the freshness fields an agent needs to reason about staleness. Minor gap: it doesn't say what an empty day or a non-matching ticker returns.

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 only 25% (only date is described in-schema), so the description must compensate, and it does: it supplies the YYYY-MM-DD format and default for date, the filter semantics for kind and ticker, and the bounds and default for limit (1–100, default 25). Only the kind enum values themselves are left entirely to 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 names a specific verb and resource ('ETF news for one day from ETFIQ's ETF News, read from SEC filings') and enumerates the exact event types covered: launches, closures, filings not yet trading, name/ticker changes, fee changes, splits. That granularity clearly separates it from siblings like etf_flows, etf_movers, or etf_profile.

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

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

It states the default behavior (latest published day, with is_latest and lag_days signaling staleness) and how to pivot to an earlier day via date, narrow to one kind via kind, or focus on one fund via ticker. It does not explicitly name a sibling to use instead for historical series or flow data, so it stops short of full when-not guidance.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description's real contribution is the fail-closed policy: it refuses rather than estimating when data is missing, and the value is tied to what ETFIQ published. That is meaningful behavior beyond annotations, though the shape of a refusal (error vs. explanatory text) is left unstated.

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 short sentences that front-load the core metric, then usage, then failure mode – no filler. The leading "Analyst and Risk Officer:" audience tag is slightly distracting but does convey intended consumers.

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 carries the return-value burden, and it only gestures at "how much of their weight" without stating form (percentage), granularity, or what accompanies it. Combined with undocumented parameters, an agent can guess the intent but not the exact calling convention.

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% and both parameters are opaque single letters, a and b, with no descriptions or enums. The description only implies they are the two funds in the pair; it never says whether they take tickers, fund names, or page slugs, nor whether order matters for the result.

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 concrete verb+resource: the shared weight two funds hold in common, sourced from the ETFIQ comparison page for that pair. It is clearly narrower than generic siblings such as etf_compare or etf_holdings, though it never names a sibling explicitly to sharpen that boundary.

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 use case ("whether two ETFs are the same thing, or whether owning both adds anything") and explicit failure conditions (pair not compared, or either holdings book incomplete). What it lacks is a named alternative for those cases – the agent must infer that etf_compare or etf_holdings is the fallback.

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, idempotent, non-destructive, closed-world behavior, and the description still adds substantial context the annotations cannot: per-number source and as-of provenance, closed-fund behavior (returns 'closed' with the day and the page's wording), and former-ticker redirection that resolves to the current fund and says so. These are exactly the edge cases an agent needs before calling.

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 scope statement is front-loaded and no sentence is pure filler — each one adds contents, edge-case behavior, or disambiguation. The benchmark sentence is dense and parenthetically overloaded, slowing parsing for a one-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?

With no output schema, the description does the work of describing return contents, provenance, and error-adjacent cases (closed funds, former tickers), and annotations cover the safety profile. The remaining gap is the unknown/invalid ticker case, which is left unstated alongside the closed-fund behavior.

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 single ticker parameter has 0% schema description coverage, so the description has to carry meaning — and it does add one important semantic: a former ticker is accepted and resolves to the fund it trades as now. It omits format specifics (casing, symbol conventions) and what an entirely unknown ticker returns, keeping it below a 5.

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 opening clause 'Everything ETFIQ publishes about one fund' gives a specific resource and scope, and the description enumerates the contents (issuer, category, sourced numbers with as-of dates, verdict, benchmark windows). It does not, however, distinguish itself from near-superset siblings such as etf_scorecard, etf_promise, or etf_benchmark, which are arguably slices of this same 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?

Usage is only implied: 'everything about one fund' suggests reaching for this when you need the whole picture rather than a slice. The one explicit disambiguation — that list_benchmarks covers ETFIQ's model-portfolio benchmarks, a different thing — is limited to a niche case and says nothing about when to prefer etf_scorecard or etf_promise instead.

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 genuine context beyond that: the full shape of the response and an explicit failure mode ('a fund the test cannot be run on says so with the reason'). It does not cover what happens for an unknown or invalid ticker, which is the remaining behavioral 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?

Front-loaded with the core question — whether one ETF delivered what its category promised — before the payload inventory. The dense enumeration of returned fields is long but each clause names a distinct output element rather than padding. It is a single run-on sentence, which costs it the top mark.

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 must carry the return values, and it does so comprehensively, including the category-level context and the untestable-fund case. Only the invalid/unknown ticker behavior and the meaning of the numeric index scale are left unstated.

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 a single required parameter at 100% schema coverage, and the schema already gives an example ('such as JEPI'), so the baseline is 3. The description only reinforces the singular scope ('one ETF'), which the schema does not state explicitly but which adds little beyond 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?

Names a specific resource ('ETFIQ Promise Index' check for one ETF) and enumerates exactly what comes back: badge (Delivered/Partly/Missed), the number behind it, its window, the fund-page sentence, plus the category's promise, test, thresholds and Promise Index. That is far more concrete than the name alone. It stops short of naming a sibling (e.g. etfiq_methodology for the test definition, etf_scorecard for broader scoring), so an agent must infer the boundary from the content list.

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

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

Usage is implied by the phrasing — this is the per-fund check of whether an ETF met its category promise — and the 'one ETF' scope signals it is not a screening tool. But there is no explicit when-to-use/when-not, and no pointer to etfiq_methodology, etf_scorecard or etfiq_page when the agent actually wants the underlying methodology or a multi-fund view.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context about what each ranking contains — that it ranks a single published number within a stated set — which is behavioral information not in the annotations. It does not say what happens with an unknown slug, or whether rankings change over time.

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 with no padding, but the lead is a vague role metaphor rather than the key fact, so the useful information (what the rankings are, and the no-argument behavior) is not front-loaded. The concrete ranking examples earn their place; the 'Strategist and Scout' framing does not.

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, two undocumented parameters and no annotations gaps to lean on, the description should explain the shape of a returned ranking and the valid slug space. It gestures at the content of a ranking but leaves the agent unable to construct a valid slug or understand what 'limit' bounds.

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%, so the description carries the full burden. It partially compensates for 'slug' by implying that supplying one selects a single ranking, but it never says what slug values exist or how to obtain them, and 'limit' is not mentioned at all. Half the parameters remain unexplained in both schema and description.

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

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

The description conveys that this returns ETFIQ's published ranked lists, or one of them, and gives concrete examples of what a ranking measures (cheapest funds in a theme, leveraged funds furthest from their multiple, buffer funds closest to their cap). But the opening framing ('Strategist and Scout') is evocative rather than specific, and the dual mode (catalog of rankings vs. a single ranking) is implied rather than stated with a clear verb+resource. Siblings like etfiq_list, etfiq_sections and etf_screen are not distinguished.

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?

'Call with no argument for the list' is a real usage instruction that tells the agent how to get the catalog versus a single ranking. Beyond that there is no guidance on when to prefer this over etf_screen, etf_movers, or etfiq_list, and no exclusions or prerequisites. Usage is implied but not routed.

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 establish read-only, idempotent, closed-world behavior, so the bar is lower. The description still adds real value beyond them: it discloses the underlying sources (19a-1 notices weighted by amount, Form N-CSR, N-PORT), states that an unread notice is never reported as 0% (a missing-data-vs-zero behavior), and disclaims that these are filing facts, not tax advice.

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 core purpose is front-loaded in the opening clause, and every subsequent clause enumerates a distinct returned element rather than restating. It is a dense single sentence, but nothing is clearly disposable given the absence of an 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 must convey the return structure, and it does — notice rows with source/window/date, the N-CSR final character with fiscal year and filing date, the side-by-side comparison, and options written from N-PORT. The missing-data caveat is a plus; only ordering/presentation details are left 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?

There is one parameter with 100% schema description coverage ('One fund's ticker, such as JEPI'), so the schema carries the semantic load. The description adds no ticker constraints or formatting guidance beyond that; baseline 3 applies.

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

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

The description names a specific resource — return-of-capital share of an income ETF's distributions plus final tax character — which no sibling tool covers. It lacks an explicit verb (it reads as a noun phrase describing output), but the scope is unmistakable.

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

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

The 'income ETF' qualifier implies when the tool applies, and the mention of distributions/tax character signals the analyst use case. However, there is no explicit when-to-use, no when-not-to-use, and no routing to a sibling such as etf_profile or etf_flows for related distribution data.

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

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

Annotations already establish readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description goes further by explaining output behavior beyond annotations: flags carry the number, date and threshold line crossed, 'none is advice,' and unpublished numbers are listed per fund rather than silently treated as zero. That last point is a meaningful disclosure an agent could not infer from the schema.

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 content is dense and mostly earns its place, but the prose is cramped and occasionally ungrammatical ('the observations to check before the funds are read one by one', 'a leveraged share'), which forces re-reading. The long metric enumeration is useful but would be far clearer as a structured list, and the opening sentence buries the verb.

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 nested object parameter, the description does the work of explaining return contents: per-fund metrics, list-level aggregates, flag anatomy, and missing-data handling. An agent could invoke this correctly and interpret the response from the description alone; only edge cases (invalid tickers, weights referencing unlisted tickers) are unaddressed.

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, giving a baseline of 3. The description adds some value by giving a concrete weights example with percent units ('{"SPY": 60, "QQQ": 40}') and stating that omitting weights yields equal weighting — a behavior the schema does not specify — but it stops short of clarifying validation or behavior for tickers that appear only in weights.

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 names a concrete role and resource: a risk check over 1 to 20 fund tickers that returns per-fund observations (net assets, fee, top-10 weight, NAV premium/discount, spread, liquidity score, leverage) plus list-level aggregates (pairwise overlap, largest fund, issuer/category shares, leveraged share). This is specific enough to distinguish it from siblings like etf_profile or etf_overlap, though it never explicitly contrasts itself with them.

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 observations to check before the funds are read one by one' implies a pre-screening workflow, and 'for 1 to 20 fund tickers' bounds the input. However, there is no explicit when-to-use versus when-to-use-a-sibling guidance (e.g., when to call etf_overlap instead of relying on this tool's overlap output).

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 establish that this is a safe, read-only, idempotent, non-destructive, closed-world operation. The description adds meaningful behavioral context: the returned metrics, inclusion of the window, return count and risk-free rate, and the precise rule for alpha_test.significant. It does not cover failure modes or ticker-validation behavior.

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

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

The description is front-loaded with the core purpose and then enumerates the returned metrics, which is justified because there is no output schema. It is dense and somewhat long, but every sentence—including the alpha significance rule—adds useful information rather than repeating 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?

With no output schema, the metric enumeration is essential and the description provides it comprehensively, along with both operating modes and the alpha significance condition. It stops short of explaining benchmark selection or error cases, but is otherwise sufficient for correct invocation.

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

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

Schema coverage is 100%, so both ticker and versus are already documented. The description clarifies that versus produces a two-ETF comparison page view, which adds slight value beyond the schema, but it gives no additional format or constraint details.

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 resource and scope: a risk/return scorecard for one ETF against its ETFIQ benchmark, or a pair scorecard when versus is supplied. It distinguishes the single and pair modes clearly, but does not explicitly differentiate itself from siblings such as compare_to_benchmark or etf_compare.

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

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

Usage is implied by the mode description: use ticker alone for one fund against its own benchmark, or add versus for a side-by-side pair. There is no explicit guidance on when this tool is preferable to sibling comparison tools, and no exclusions or prerequisites are stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds substantial behavioral detail: fees are percentages not basis points, funds lacking published data are set aside and counted rather than failed, and truncated/note/count/first explain partial-result and tie semantics. This is exactly the value-add over structured fields that earns a 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?

It is a dense but information-rich paragraph where nearly every clause carries a distinct fact (return shape, filter list, count/truncation, ties, fee units, null handling). The run-on quality and late placement of the usage guidance keep it from a 5.

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 nine parameters, the description does the work of explaining the returned structure (count, truncated, note, first) and edge-case handling, making it largely complete. The absence of explicit limit handling and of specific sibling routing leaves a minor gap.

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 only 44%, but the description documents desk, issuer, max_fee_pct, min_assets_usd, tracks, min_yield_pct, pays, and sort — most of the nine parameters — with meaningful semantics (e.g., fee percentages not bps, yield as 12-month percent). Only limit is left implicit via the truncation discussion, so it nearly compensates for the low schema coverage.

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

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

The description clearly states the tool returns every fund matching supplied filters, each with net assets and the source/date of that figure. This is a specific resource (an ETF screening result set) with the returned payload named. It doesn't explicitly name the sibling tools it competes with (etf_search, etf_compare), but the scope 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?

"Use for 'find me all X' and 'cheapest X' questions rather than repeated searches" gives an explicit when-to-use and contrasts against an alternative approach. It's clear context without naming specific sibling tools or exclusion cases, so it stops 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?

Goes well beyond the readOnly/idempotent annotations to disclose non-obvious behavior: exact-match-only semantics with refusals that explain why, a refusal implying ETFIQ does not publish the fund, ticker-change resolution, closed-fund pages with a closure date, and SEC-filed non-trading entities landing in a separate 'filed' bucket with counts rather than results. This is exactly the behavioral 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?

Purpose and lookup keys are front-loaded, and nearly every clause contributes distinct behavior (refusals, ticker changes, closures, filed-only entities). Some sentences are heavily nested and the final clause about 'how many are filed and how many trade' is dense, but there is 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?

With no output schema and no param documentation, the description compensates well on edge-case return behavior but says nothing about the shape of a normal result, what 'limit' bounds, or what 'desk' scopes to. Adequate for picking the tool, incomplete for calling it confidently.

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% and three parameters exist, yet the description only implicitly characterizes 'query' (ticker, fund name, or a word from the name). Neither 'desk' nor 'limit' is mentioned anywhere, so two of three parameters are undocumented in both the schema and the description.

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

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

States a concrete verb and resource ('Find US listed ETFs') plus the three accepted lookup keys (ticker, fund name, word from the name). It also distinguishes itself from the sibling that continues the workflow ('etf_profile then takes the ticker it returns'), so an agent can separate search from profile 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?

Explicitly frames the tool as the entry point for loosely remembering a fund name and names etf_profile as the follow-up, which is real routing guidance. It does not compare against other candidates like etf_screen or the broader etf_* lookups, and gives no exclusion criteria, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description usefully reinforces the closed-world trait by promising the 'whole published set rather than a sample', but it says nothing about pagination, result size caps, or behavior for an unrecognized theme.

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 tight sentences with the resource and ordering front-loaded before the use-case sentence. The 'Scout and Strategist:' persona prefix is minor noise that adds no operational value but costs little.

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 two-parameter read tool with no output schema, the description covers what comes back and in what order, which is most of the burden. It still omits theme string format, the role of limit, and empty-result behavior, leaving gaps an agent would hit on first use.

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

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

With schema coverage at 0%, the description should carry parameter meaning, and it only implies 'theme' through phrasing. Worse, 'returns the whole published set rather than a sample' sits in tension with the undocumented 'limit' parameter, leaving the agent unsure whether limit truncates the set or is ignored.

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 names a specific resource (every US-listed fund in a theme), the ordering (largest first), and the payload (fees charged, share already in the S&P 500), so an agent knows exactly what it gets back. It does not distinguish itself from the near-identical sibling 'etf_themes', which an agent could easily confuse with this 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?

It gives concrete triggering questions ("what X ETFs are there", "top X ETFs"), which is clear when-to-use guidance. It stops short of naming alternatives such as etf_screen or etf_search, or stating when a filtered screen is preferable to enumerating the whole theme.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety and repeatability are covered without description text. The description adds the useful behavioral detail that each theme comes back with a fund count, but says nothing about ordering, size, or whether the list is exhaustive/paginated.

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

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

Two short sentences with zero filler, and the payload description is front-loaded before the usage instruction. The 'Strategist:' prefix is minor noise that adds no meaning for an 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?

For a zero-parameter lookup with no output schema, the description covers what comes back (theme names plus fund counts) and what to call next. Only the return shape and any result-size behavior are left implicit, which is a small gap at this complexity.

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

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

The tool takes no parameters and the schema is an empty object at 100% coverage, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-level explanation is needed or missing.

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 concretely that the tool returns every theme ETFIQ publishes plus a fund count per theme, which is more specific than the title 'All themes'. It implicitly distinguishes itself from the sibling etf_theme by positioning this as the enumeration step, though it never names the contrast explicitly.

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?

'Call when unsure what a theme is called, then etf_theme' gives a clear trigger condition and an explicit follow-up call in the sibling tool. It stops short of stating when not to use it (e.g., if you already know the theme name, skip straight to etf_theme).

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, closed-world, non-destructive, so the safety profile is covered. The description adds genuinely useful context by saying unpublished numbers come with an explanation of why, and that the lead sentence is sourced from the fund's trading page — but it says nothing about format, staleness, or how missing data is signaled in the response.

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 lead clause 'What it costs to trade one ETF' is well front-loaded, but the rest is a single dense run-on packing four separate metrics plus a sourcing note. Splitting into 'returns X, Y, Z' plus a separate provenance sentence would be far easier to scan.

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

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

No output schema exists, so the description must carry the return-value burden. It does enumerate the metrics, but phrases like 'ETFIQ's own premium from NAV and closing prices with its window' and 'IQ Liquidity Score on a fixed 0 to 100 scale' are jargon-dense and leave the shape of the response (fields, units, how 'why not published' is conveyed) ambiguous.

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 only one parameter, ticker, and schema coverage is 100% with an example ('JEPI') already given. The description adds no constraint, format, or validation detail beyond the schema, so baseline 3 applies.

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

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

The description makes the subject clear — cost-of-trading metrics (liquidity score, spread, premium/discount to NAV) for a single ETF — but it is phrased as a list of data fields rather than a verb+resource statement. It never distinguishes this tool from nearby siblings like etf_profile, etf_scorecard, or etf_compare, which likely also expose some of these fields.

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?

There is no guidance on when to call this versus the many other per-ETF tools in the sibling list, and no mention of prerequisites. An agent must infer usage purely from the field inventory.

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, idempotent, closed-world, non-destructive, so the description is free to add real behavior: at most three results, best-first ordering, match score 0-100 with a reason, the answered=false sentinel, and the deterministic matching order (exact phrase, exact pair, named entity, then word overlap). What it omits is threshold definition and what happens when both path and query are supplied.

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 core purpose and the answered=false fallback are stated up front, but the middle is a 16-item enumeration of page types that no agent can hold in working memory and that the examples already convey. It is dense and every sentence is roughly on-topic, yet the list is longer than it earns.

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 does the heavy lifting by describing the card payload (title, address, dated lead sentence, JSON-twin numbers, score, reason). The remaining gap is numeric specifics: what the threshold is and whether fewer than three results can be returned without answered=false.

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, but the description adds interpretive value by explaining that query is free-form reader language whose matching is deterministic and ordered, and that path is an alternate selector for one page's card rather than an additional filter.

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 — find the ETFIQ page that answers a question — and enumerates the page kinds it covers, plus the card contents. An agent can distinguish this from etf_search, etfiq_page, or etf_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?

Gives explicit when-to-use criteria ('any question one ETFIQ page answers') with four concrete example questions, plus a when-not path: 'answered is false when no page reaches the threshold: then answer with the other tools.' It also names the path-vs-query alternative for reading a single known page.

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 read-only and idempotent annotations already covering safety, the description adds substantial behavioral context: it enumerates the returned data, explains that basis marks pre-freeze numbers as hypothetical, and clarifies that only published benchmarks are available. It does not describe error behavior for invalid ids, but that is a minor 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 front-loaded with the core purpose and then efficiently enumerates returned fields. The long first sentence is dense but earns its space because there is no output schema; minor improvement would come from splitting it 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?

Because there is no output schema, the description needs to explain return contents, and it does so thoroughly: methodology rule, funds and weights, SEC series ids, expense ratios, and all computed statistics by window. It is nearly complete for a read-only getter, with the main omission being how an agent should discover valid ids.

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%, so the description must carry parameter meaning. It does so by explaining that the single required id can appear as 'etfiq-strategic-60' or 'strategic-60', giving useful format examples beyond the bare string schema, though it does not explain where ids come from or constraints on invalid values.

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

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

The description states a specific resource and scope: one ETFIQ benchmark in full, including its methodology rule, fund weights, and computed statistics. It distinguishes itself from broader tools by emphasizing 'one ... in full' and 'Serves the published benchmark only; it cannot be customised.'

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

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

Usage is implied: use this to retrieve details for a known benchmark id. The description says it serves only published benchmarks and cannot be customised, which is a useful boundary, but it does not explicitly name alternatives such as list_benchmarks for discovering ids or compare_to_benchmark for comparison.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds behavioral context those hints cannot carry: benchmarks are identical for everyone and never a recommendation, customisation requests and buy/sell advice are refused, and custom portfolio work is redirected to build_portfolio. That refusal semantics is actionable for an agent deciding whether to call at all.

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?

It is dense but front-loaded: definition first, then filter vocabulary, then usage routing, then exclusions and boundaries. Every clause carries information, though the opening sentence is a long run-on and the sibling-routing tail is packed into two heavy sentences that could be split.

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 should ideally hint at the return shape (e.g. benchmark identifiers/names and families to feed into get_benchmark); it implies this via 'then get_benchmark for one' but never states what a listed item looks like. Otherwise it is complete for a read-only, zero-required-parameter listing tool.

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

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

Schema coverage is 0% — neither 'band' nor 'family' is described in the schema — so the description must carry the load and does: family values are enumerated (strategic, tax-aware, factor, income, tactical, thematic) and 'band' is explained with concrete formats ('moderate', '60', or "all stocks"). This is meaning the agent could not derive from the bare string properties.

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 concrete verb+resource (listing ETFIQ benchmark definitions) and immediately characterizes what a benchmark is — 'published, rules-based yardsticks for model portfolios... a written rule over broad, low-cost ETFs'. It explicitly separates itself from sibling tools (get_benchmark for one entry, etf_profile for a fund's own benchmark, etfiq_methodology for how it is chosen), so an agent can route correctly 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 gives an explicit trigger ('use when asked which benchmark measures a kind of model portfolio, then get_benchmark for one') and names the negative cases: a fund's own benchmark lives in etf_profile, methodology in etfiq_methodology, and custom portfolio construction in build_portfolio. When-to-use, when-not-to-use, and the successor tool are all 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 readOnly, idempotent, non-destructive, closed-world. The description adds context the annotations cannot: results are hypothetical/paper-only, never advice, and it enumerates the row contents (risk, benchmark, paper/back-test windows, holdings, signal pill, next dates, second-source rebuild agreement). It does not mention pagination or size limits, so not a 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?

Purpose and ordering are front-loaded and every clause carries information (row fields, caveats, next-step tools). The single dense sentence enumerating row fields is long but earns its place given there is no output schema; minor cost is density over scannability.

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 compensates by listing what each row contains and adding the hypothetical/paper disclaimer. It is complete enough to call correctly, though it says nothing about result volume or pagination behavior for a potentially long strategy list.

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

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

Schema coverage is 100% and the schema already documents the group field with its allowed values (core, countries, 2x-shelf, balanced, income). The description only restates 'filter by group'; the strategy-type words in the description are not group values, so this adds no real syntax beyond the schema. 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: listing ETFIQ Strategy Lab strategies, each 'a written rule over ETFs', with defined ordering ('ranked by paper return since the paper start'). It clearly differentiates itself from the slug-based siblings strategy_signals and strategy_record.

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 sequencing ('Call first, then strategy_signals or strategy_record with a slug') and the optional narrowing condition ('Filter by group'). An agent knows exactly when to use this vs the two follow-on tools and what to pass next.

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 read-only, idempotent, non-destructive annotations, the description discloses the returned content in detail: real-days-only numbers, paper record, full back-test, benchmark scorecard, modelled costs, turnover, and second-source check. It also warns that the back-test never ranks and that the record is labelled hypothetical, which is valuable 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?

The purpose is front-loaded, but the description is a dense, long run-on sentence with multiple embedded clauses. It is informative yet less scannable than it could be, and it repeats the slug source already present in 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?

With no output schema, the description does a strong job explaining the major sections and caveats of the returned record. It does not describe the exact response shape or field-level structure, but it is complete enough for an agent to understand what calling the tool will yield.

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

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

The schema already has 100% description coverage and states that the slug comes from strategy_list. The description repeats that source but adds no syntax, format, or validation 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?

The description identifies a specific resource — one Strategy Lab strategy's record — and clarifies that it is labelled hypothetical and includes both paper and back-test data. It names strategy_list as the source of the slug, but it does not explicitly distinguish itself from other strategy-related siblings such as strategy_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?

It gives clear workflow guidance: take a slug from strategy_list and read the paper record before the back-test. It does not state when to use this instead of alternatives like strategy_signals or compare_to_benchmark, so some routing inference remains.

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

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

The description goes well beyond the annotations: it states the blotter is hypothetical ('what the rule would have traded at the next close'), that ETFIQ places no orders, and adds an anti-instruction caveat about the content. It also discloses the blotter_limit default (10) and bounds (0 to 50), which annotations cannot convey. This is exactly the kind of behavioral context that lowers the burden on readOnlyHint/idempotentHint.

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 scope statement is front-loaded and every clause carries information, but the opening sentence is a long run-on list of returned fields that takes effort to parse. Nothing is redundant, yet splitting the field enumeration from the paper-only caveat would improve 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?

There is no output schema, so the description must carry the return contract, and it does: it enumerates signals, holdings percentages, dates, last moves, and the blotter with its limit. Combined with the paper-only disclaimers, an agent can decide on and call this tool without further information.

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 50%: slug is documented in the schema as 'A slug from strategy_list', while blotter_limit has no schema description at all. The description compensates for that gap by giving the parameter's meaning, its range (0 to 50), and its default (10), which the schema omits. It does not explain slug format beyond the source tool, so a 4 rather than 5.

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 names a specific resource (one Strategy Lab strategy) and enumerates the returned content: per-fund signals with distance from the line, target holdings in percent, next signal and trade dates, last moves, and the paper blotter. That is far more than a restatement of the name. It does not distinguish itself from the sibling strategy_record, which plausibly overlaps, so it falls short of a 5.

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?

Useful context is implied: the tool is a read of 'today's state' and requires a slug 'from strategy_list', which tells the agent where the identifier comes from. However, there is no explicit statement of when to use this versus strategy_record or strategy_list, and no exclusion conditions, so usage is only inferred.

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