Bullrun

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

Despite the readOnlyHint annotation, the description explicitly states 'Read-only' and adds a crucial caveat about provider holdings being partial top-holdings samples, warning that coverage is not guaranteed. This goes beyond the annotation and helps the agent set correct expectations.

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, zero filler. The first sentence front-loads the action and return types; the second provides a necessary caveat. Every clause contributes meaning.

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

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

Given the output schema exists, return values need no description. The description covers inputs (two to ten ETFs), the algorithm (weighted overlap), the key caveat (partial holdings), and the safety profile (read-only). This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 50% (only 'tickers' has a description). The description reinforces the range of tickers but completely omits any explanation of 'topSharedLimit' (e.g., that it controls the number of largest duplicate exposures returned). The description does not compensate for the undocumented parameter.

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

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

The description states a specific verb ('Compare'), a specific resource ('ETFs'), and a precise scope ('two to ten'), then enumerates the exact outputs (pairwise shared holdings, weighted overlap, etc.). This clearly distinguishes it from sibling tools like compare_etfs, which likely covers broader comparisons.

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

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

The description implies usage for overlap analysis and clarifies the number of ETFs, but it does not explicitly mention when to prefer this tool over alternatives like compare_etfs, nor does it state exclusions or prerequisites. The context is present but not differentiated from siblings.

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

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

The description explicitly discloses read-only behavior (consistent with readOnlyHint annotation), requires OAuth read:portfolios, and warns that partial provider holdings make duplicate exposure a lower bound. This goes beyond the annotation by adding a reliability limitation and auth requirement.

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 filler; purpose is front-loaded, and each sentence adds behavioral or technical context. Efficient and well-structured.

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

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

The tool is well-covered: purpose, inputs (implicitly), required auth, read-only status, and a key limitation are all disclosed. The presence of an output schema means return values don't need description. No significant gaps remain for a read-only analysis 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 only 40% (portfolioId and candidateTicker have descriptions), while days, candidateWeightPct, and includeLookThrough lack explicit semantics. The description broadly references price-history and look-through but doesn't map these to parameters or explain units/meaning of candidateWeightPct or days.

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

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

The description clearly states the tool analyzes an ETF candidate against a user's portfolio, combining price-history fit metrics (correlation, beta, pro-forma volatility) with holdings look-through for duplicate exposure. This distinguishes it from sibling tools like analyze_etf_overlap and get_portfolio_analytics.

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

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

The description implies use when evaluating a candidate ETF for a specific portfolio, mentioning the look-through and coverage limitations. It names the required OAuth scope and read-only nature, providing clear context, though it doesn't explicitly contrast with alternatives like analyze_etf_overlap.

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

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

Beyond the readOnlyHint annotation, the description adds meaningful behavioral context: leaders are mechanical extrema (not recommendations), and currency/partial-holdings caveats are explicit. This helps the agent understand output limitations and interpretation, going beyond the annotation.

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

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

Three dense sentences: the first delivers the core function, the second preempts misinterpretation of 'leaders', and the third flags caveats and read-only nature. No redundancy or filler.

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

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

Given the presence of an output schema and readOnlyHint annotation, the description adequately covers purpose, scope, and interpretive caveats. It does not explain performanceDays or error conditions, but those are partially represented in the schema and output schema, so the overall context is sufficient.

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 33%, so the description must compensate. It lists the modules that map to the 'include' enum and states the ticker count range, adding meaning to those params. However, it completely omits the 'performanceDays' parameter, leaving its semantics to the schema's numeric constraints alone.

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

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

The description states a specific verb ('Return'), a resource ('two to ten ETFs'), and a clear scope ('normalized side-by-side comparison across selected modules'). This distinguishes it from siblings like get_etf_snapshot or analyze_etf_overlap by emphasizing multi-ETF comparison.

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

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

The description clearly implies when to use the tool (comparing multiple ETFs across modules) and provides a caution about leaders being mechanical extrema, but it does not explicitly name alternative tools or state when not to use it. This matches 'clear context, no 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 only indicate non-read-only and non-destructive. The description adds crucial context: draft-only (never changes live positions), requires OAuth write:drafts scope and Bullrun Pro account, and the draft appears under 'Pending AI drafts' after creation. This goes well beyond the sparse annotations.

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

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

The description is front-loaded with purpose and usage context. It is fairly long but every sentence provides necessary information (scope, distinction, behavior, authentication, vague brief handling). Could be slightly more compact without losing clarity, but overall well-structured.

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

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

Given the tool's complexity (creation with multiple options), the description covers all essential aspects: when to use, what it does, authentication requirements, draft lifecycle, alternative tool, universe constraints, and vague brief handling. No output schema needed as the description explains the outcome (draft saved and viewable).

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value: explains the prompt parameter's optional behavior (server-collected if omitted), clarifies the instrumentUniverse default (mix unless specified), and provides context for the starting cash and max positions defaults. A slight improvement over the schema alone.

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 explicitly states the tool builds or proposes a brand-new portfolio from a natural-language brief. It uses specific verbs like 'BUILD' and 'PROPOSE', clearly identifies the resource (portfolio draft), and distinguishes itself from the sibling create_position_draft.

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 when-to-use guidance ('when the user wants you to BUILD or PROPOSE a brand-new portfolio'), alternative tool for existing portfolios (create_position_draft), and handling of vague briefs with a quick multiple-choice question strategy.

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 minimal annotations (readOnlyHint=false, destructiveHint=false) by disclosing the draft-only lifecycle: saved to user's account, appears under 'Pending AI drafts', user must explicitly accept or discard, and never changes live positions. It also explains the unresolved-ticker behavior (returned in `unresolved` and skipped), adding valuable context.

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

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

The description is long but every sentence earns its place: usage context, sibling distinction, gating, draft lifecycle, universe constraints, and alternative tool. It is front-loaded with 'Use when...' and contains no fluff or repetition.

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

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

Despite no output schema, the description covers the essential lifecycle (draft saved, user review, accept/discard), unresolvable ticker handling, and prerequisites. It doesn't explicitly describe the success response structure (e.g., draft ID), but given the tool's moderate complexity and the detail provided, it is nearly complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning by explaining weight versus amount mode, cash handling (remainder held as cash, normalisation), and cashPct overriding the weight-remainder rule. This goes beyond the schema's per-parameter descriptions, though not dramatically.

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

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

The description states a specific verb ('persists') and resource ('a REVIEWABLE paper-portfolio draft') with clear scope: exact tickers supplied by the user, sized by weight or USD amount. It explicitly contrasts with create_portfolio_draft by stating it does NOT use the LLM and never re-selects tickers, making sibling differentiation strong.

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 when-to-use ('when YOU have ALREADY decided the exact holdings') and when-not-to-use ('For a vague brief where the model should pick, use create_portfolio_draft instead'). It also clarifies gating (not Pro-gated), required OAuth scope, and the need to confirm tickers in Bullrun's universe.

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

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

Annotations already indicate not read‑only and not destructive. The description adds that the tool is draft‑only and never changes live holdings, clarifying the write behavior. It also mentions required auth scope and account type. Slightly more detail on error handling would push it higher, but the current disclosure is strong.

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

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

The description is front‑loaded with usage guidance and packs dense information. While it is longer than a single sentence, every sentence adds value. Could be slightly streamlined, but overall highly efficient.

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

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

For a tool with 3 well‑documented parameters and no output schema, the description covers purpose, usage, behavior, parameter details, and sibling differentiation. It doesn't describe the response format, but given the tool's simplicity (draft creation), this is adequate.

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 covers 100% of parameters. Description adds value by explaining the instrumentUniverse parameter ('stocks only, ETFs only, or a mix'), advising to use list_portfolios for portfolioId, and noting default value for maxPositions (1 for single idea, default 3). This exceeds the baseline of 3 for high 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 generates reviewable draft suggestions for adding positions to an existing portfolio, using specific verbs like 'generates REVIEWABLE suggested additions'. It explicitly distinguishes from siblings by naming create_portfolio_draft and get_portfolio_analytics.

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

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

The description specifies exactly when to use this tool (e.g., 'when the user asks what to BUY or ADD to an EXISTING portfolio' and gives example queries). It also tells when not to use it (for new portfolios or specific ticker checks) and provides prerequisites (OAuth scope, Bullrun Pro) and pre-invocation steps (confirm portfolio with list_portfolios).

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

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

Annotations declare readOnlyHint=true, and description reinforces 'Read-only' and details every output field, going beyond annotations. No contradictions.

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?

Concise at 3-4 sentences, front-loaded with purpose ('discover... BEFORE attempting an action'), and well-structured without waste.

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

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

Despite no output schema, the description comprehensively covers all returned aspects (auth, identity, Pro, scopes, usage, tool map). Complete for a discovery 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?

No parameters; schema coverage is 100%. Description compensates by detailing the output, though param semantics are not applicable. Baseline 4 for zero parameters.

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

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

The description clearly states the tool discovers account capabilities and lists specific information returned (authentication, identity, Pro status, OAuth scopes, portfolio usage, tool entitlements). It distinguishes from siblings as a pre-action check rather than a data retrieval 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?

Explicitly advises calling this first when a draft/write tool might be gated, or to confirm the acting account. Provides clear when-to-use guidance and implies not for other purposes.

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

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

Annotations already provide readOnlyHint=true, and the description confirms "Read-only". The description adds that the tool returns "speaker-tagged" chunks and supports optional filtering, which goes beyond the annotation. No contradictions or missing critical behavioral traits (e.g., no pagination detail, but acceptable given the simplicity).

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

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

Two sentences: the first succinctly describes the action and options, the second explains the use case. Every word earns its place; no redundancy or filler.

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

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

The tool has 6 parameters (all documented in schema) and no output schema. The description explains the purpose and use case adequately. It could mention that results are ordered by speaker or time, but omitting that is a minor gap given the simplicity. The description is complete enough for an agent to understand what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the purpose of filtered chunks (qualitative judgment) and emphasizing the "exact Bullrun ticker" requirement. It also frames the optional filters (fiscal period, search text) in the context of finding specific transcript content, which helps an agent select parameters meaningfully.

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

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

The description clearly states the verb "Fetch", the resource "speaker-tagged earnings-call transcript chunks", and the specific scope "for one exact Bullrun ticker". It distinguishes the tool from its siblings (which are portfolio, position, and financial metrics tools) by focusing on qualitative transcript data.

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

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

The description explicitly tells the agent to use this for "management guidance language, analyst Q&A, and qualitative judgment that is not visible in financial statements". This provides clear context for when to invoke this tool over siblings like get_financial_history or get_forward_estimates. It does not explicitly state when not to use it, but the positive guidance is sufficient.

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

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

With only readOnlyHint=true, the description adds substantial behavioral context: data sources (latest stored holdings, Bullrun mappings), explicit statement about factor/thematic unavailability, and how coverage metrics prevent misrepresentation of partial data. It also reaffirms read-only. No contradiction with annotations.

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

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

Three concise sentences, each adding distinct value: what it calculates, data-source caveat, and coverage interpretation. No fluff or duplication of schema defaults. Front-loaded with the primary purpose.

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

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

Given the existence of an output schema and readOnlyHint, the description covers key context: input basis, limitations, and partial-data handling. It is sufficiently complete for a read-only exposure calculation tool without needing to enumerate return fields.

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

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

Schema description coverage is only 33% (only ticker has a description). The description partially compensates by naming sector/country/currency/asset, which maps to the types enum, but it does not explain the limitPerType parameter or its effect on coverage. Some meaning is added, but not enough for a low-coverage 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 starts with a specific verb ('Calculate') and clearly identifies the resource (ETF exposures from latest stored holdings and Bullrun mappings). It lists the exposure dimensions (sector, country, currency, asset), distinguishing it from siblings like get_etf_holdings or get_etf_risk.

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

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

The description implies its use case (calculating exposures) and notes that factor/thematic look-through are unavailable, which is an exclusion. However, it does not explicitly mention when to use this tool over alternatives or reference sibling tools, so guidance is only implied.

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

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

The description adds valuable behavioral context beyond the readOnlyHint: filters match exactly and a guessed string returns zero rows, making it look like no such ETF exists. It also discloses the default exclusion of long tails, which is non-obvious. This goes far beyond the annotation.

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

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

Two dense sentences, front-loaded with the core purpose. Every sentence provides essential information—what, when, and the exact-match caveat—with no filler or redundancy.

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

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

The description covers the tool's purpose, usage timing, behavioral caveats, and default facet handling. An output schema exists, so return structures are presumably documented. Given the tool's simplicity and the rich sibling context, this is complete.

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

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

The schema descriptions already cover all three parameters (limit, facets, search) in detail, including defaults and behavior. The description reinforces the facets default and mentions long tails, but it does not add significant new parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states that the tool lists exact values accepted by categorical filters on search_etfs and screen_etfs, distinguishing it from those sibling tools. The verb 'List' and explicit resource make the purpose unambiguous.

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

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

It explicitly instructs to call this tool first whenever a filter value is not already known to be valid, which is a clear when-to-use directive. It also notes that long-tail facets (fundFamilies, industries) are excluded by default and should be requested explicitly, providing practical guidance.

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

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

The annotation readOnlyHint: true is consistent with the description's "Read-only" statement, so no contradiction. The description adds value beyond annotations by clarifying the fund-vs-listing scope, the ability to resolve from a ticker to its ISIN, and that ratios are in percentage points. This provides useful behavioral context not present in the annotations.

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

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

The description is three sentences, front-loaded with the core concept "Resolve one FUND rather than one listing." Every sentence adds value: scope, return fields, use cases, and unit clarification. No redundant or filler content.

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 moderate-complexity tool with an output schema and readOnly annotation, the description covers the essential context: the fund-level scope, input flexibility via ISIN or ticker, key returned fields, use cases, and a unit caveat. It is complete without needing to explain the output schema details, which are already structured.

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?

Both parameters have detailed descriptions in the input schema (including examples and the note to provide either isin or ticker), so schema coverage is 100%. The tool description adds little parameter-specific meaning beyond reinforcing the either-or relationship. Baseline of 3 is appropriate because the schema already carries the semantic weight.

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 resolves a FUND rather than a listing, and enumerates the returned data (identity, costs, index, distribution policy, wrapper type, and venues). It distinguishes itself from listing-specific siblings like get_etf_snapshot by the "rather than one listing" contrast, making the purpose unmistakable.

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

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

Explicit use cases are given: when the user quotes an ISIN, asks which ticker to buy, or when multiple tickers may share the same underlying fund. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough to guide selection among siblings.

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

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

The description adds significant behavioral context beyond the readOnlyHint annotation: it explains the response structure (provider count, stored count, covered weight, completeness flag), warns to treat isComplete=false/null as partial data, and discloses the future availability of historical selection. This gives the agent essential interpretation guidance.

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

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

The description is succinct at four sentences, with the core purpose stated first and additional essential caveats in the following sentences. Every sentence adds material information without redundancy or padding, and it is well-structured for quick parsing.

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

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

Given the presence of a full output schema, an annotation for read-only behavior, and complete schema descriptions for all parameters, the description covers the remaining critical context: pagination mechanics, data completeness interpretation, and known limitations. No important gaps remain.

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

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

Schema description coverage is 100% for all three parameters, so the schema already documents each field meaning. The description adds almost no parameter-level detail beyond what is in the schema, except reinforcing the 'opaque cursor' nature, which the schema also mentions. Baseline score of 3 is appropriate.

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

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

The description states a specific action ('Return the latest stored ETF holdings snapshot') with a clear resource ('ETF holdings') and key mechanism ('opaque cursor pagination'). It distinguishes itself from sibling tools like get_etf_exposures or get_etf_snapshot by focusing on the holdings list and its pagination, making 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?

The description clearly indicates this tool provides the latest stored snapshot and explicitly notes that historical as-of selection is not yet available, giving context on when to use it. However, it does not name alternative tools or state when not to use this tool, so it lacks explicit exclusion guidance.

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

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

Beyond the readOnlyHint annotation, the description adds significant behavioral detail: deduplication to one row per fund rather than per venue listing, the ordering by fee, the default UCITS domicile restriction, the fact that fees are percentage points, and the explicit statement that the response reports how many funds publish no fee so a 'cheapest' claim is never made over silently omitted funds. This is excellent transparency about the tool's logic and limitations.

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

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

The description is concise yet information-dense. Every sentence adds value: the core purpose, the dedup rule, the domicile default, the optional indexKey behavior, and the fee reporting nuance. It is front-loaded with the main question and efficiently covers the key behaviors without redundancy.

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

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

With an output schema present, the description needs not explain return structure, but it covers all essential behavioral context: what is returned, how results are ordered and deduplicated, the default scope, the optional indexKey behavior, and the handling of missing fee data. This is a complete and self-sufficient description for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description reinforces the indexKey behavior ('Omit indexKey to list the available index families') and mentions the UCITS default that maps to the scope parameter, but it does not add substantial new parameter-level meaning beyond what the schema already states. This meets the baseline for full 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 opens with a concrete question it answers ('what is the cheapest way to track <index>?') and then states exactly what it returns: every fund tracking one index, ordered by fee, deduplicated by fund rather than venue listing. This clearly distinguishes it from siblings like compare_etfs or search_etfs by specifying fund-level deduplication and fee ordering.

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 intended use case is immediately clear ('Answer...'), and it provides helpful context such as the UCITS-buyable domicile default and the optional indexKey omission for listing index families. However, it does not explicitly name alternative tools or state when not to use this tool, leaving that to the agent to infer from sibling names.

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

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

Annotations declare readOnlyHint: true, which aligns with the description's explicit 'Read-only'. Beyond this, the description adds valuable context: it specifies that calculations use stored daily close prices, that results are 'price-return risk, not distribution-adjusted total-return risk', and how benchmarkTicker enables relative metrics. While it doesn't address rate limits, output format, or error conditions, the mix of annotation and description provides good transparency for a read-only calculation tool. The 'Read-only' repetition is redundant with annotation but overall multiple behavioral constraints are disclosed.

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

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

The description is concise and front-loaded: it leads with the primary purpose, enumerates outputs, and closes with a caveat and read-only status. Every sentence adds value—no redundant filler. It is appropriately sized for a tool with 4 parameters and a clear output schema. The structure efficiently communicates both scope and limitations.

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

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

Given the presence of a full output schema, an annotation for read-only, and sibling tools that clarify its positioning, the description is complete enough. It explains the calculation basis, the optional benchmark functionality, and the key limitation (price-return vs distribution-adjusted). It doesn't need to explain return values because output schema exists. For a read-only analytics tool, this is thoroughly specified.

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

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

Schema description coverage is 100%, meaning every parameter (ticker, days, benchmarkTicker, riskFreeRatePct) has a detailed description in the schema. The tool description does not add additional semantic meaning beyond what the schema provides; it merely recaps the outputs in relation to benchmarkTicker. The baseline of 3 is appropriate since the schema already documents parameters thoroughly, and the description adds minimal extra value. The description does clarify that benchmarkTicker enables specific calculations, which is a slight addition, but not enough to raise the score.

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

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

The description clearly states the tool's function with specific verbs ('Calculate') and identifies the exact resource ('stored daily close prices'). It enumerates a comprehensive list of outputs (drawdown, volatility, VaR, ratios) and distinguishes itself from sibling tools that analyze overlap, holdings, or timeseries. The explicit 'Read-only' declaration and the 'price-return risk' clarification further refine its scope, positioning it distinctly among the sibling tools like get_etf_timeseries and get_etf_exposures.

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

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

The description gives implicit usage guidance by detailing optional benchmarkTicker for relative risk metrics and explicitly stating the calculation basis ('from stored daily close prices'). While it doesn't say 'use this instead of X', it implies when to use versus siblings like get_etf_snapshot (current state) and get_etf_exposures (composition). However, since there is no explicit 'use when' statement, a score of 4 might be more appropriate. Re-evaluating: the guidelines dimension rewards explicit when/when-not, but a clear context and functional boundaries are provided. Given the sibling tools, the description sufficiently implies its purpose. I'll keep it at 5 because it clearly delineates what the tool does not do (distribution-adjusted total-return risk) and what it adds with benchmarkTicker.

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

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

Beyond the readOnlyHint annotation, the description adds useful behavioral details: unrequested modules are omitted, requested-but-unavailable modules are named explicitly, and ratios use percentage points. This provides insight into output behavior without contradicting the annotations.

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

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

The description is three sentences, each containing specific, non-redundant information. It is front-loaded with the core purpose and avoids filler or repetition of schema 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?

Given the output schema exists, the description need not explain return values in detail. It adequately covers modularity, exactness, unavailable-module behavior, units, and read-only nature, making the tool's behavior clear for a snapshot tool with only two parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for the 'include' parameter by explaining its effect on the response (modules omitted or named if unavailable) and by listing module examples. It also clarifies 'exact' ticker matching beyond the schema's 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 uses a specific verb ('Fetch') and resource ('modular snapshot for one exact ETF listing'), which clearly distinguishes it from sibling tools like get_etf_holdings or get_etf_risk. It communicates both the action and the exact scope of the 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?

The phrase 'one exact ETF listing' implies the tool is for precise lookups, but it does not explicitly state when to prefer this tool over alternatives, nor does it mention exclusions or alternative tools. The usage context is implied, not explicitly contrasted with siblings.

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

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

Beyond the readOnlyHint annotation, the description discloses important behaviors: unavailable series are named explicitly and never approximated, and series are returned only when source data or explicit benchmark ticker exists. This adds significant transparency about conditional behavior and data quality, exceeding what annotations provide.

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

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

The description is three concise sentences: core function, conditional behavior, and read-only safety. Every sentence adds distinct value with no redundancy or fluff.

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

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

Given the tool's complexity, output schema existence, and readOnly annotation, the description covers the key behavioral rules not in the schema. It explains conditional availability and the no-approximation policy, making the tool complete for selection and invocation without needing return details.

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

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

Schema description coverage is 57%, so the description compensates by clarifying the series parameter (never approximated) and benchmarkTicker (explicit ticker needed). It does not explain startDate, endDate, or limit, but these are relatively self-explanatory or covered by schema defaults.

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

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

The description clearly states the tool fetches ETF price or price-return history at daily, weekly, or monthly intervals. It specifies the exact resource (ETF time series) and the action (fetch), distinguishing it from siblings like get_etf_holdings or get_etf_snapshot, which focus on other data types.

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

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

The description implies when to use this tool (for time series data) and provides context about when additional series like NAV or benchmark are available. However, it does not explicitly name alternative tools for other use cases or state when not to use this tool, so it lacks explicit exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true; description adds details on return structure (grouped rows, consistency checks) and ticker format warnings, but does not contradict 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?

Four sentences with no redundancy; front-loaded with purpose, then return details, then usage guidance. Every sentence adds value.

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

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

Describes output components (income statement, balance sheet, etc.) comprehensively despite no output schema. Covers key input aspects. Minor lack of details on pagination or limits beyond year range.

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

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

Schema has 100% parameter description coverage; description adds high-level context (e.g., '1-15 years' for years) but does not significantly enhance parameter understanding 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?

Description uses specific verb 'Fetch' and resource 'historical financial statements' for one ticker, clearly distinguishing from siblings like get_forward_estimates and get_earnings_call_transcript.

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

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

Explicitly states when to use: 'Use this when evaluating multi-year revenue/net-income growth, margin trajectories, leverage, cash flow quality, or whether a stock passed a rule such as 10% revenue and net-income growth every year.' Provides clear context.

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

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

The description adds significant value beyond the readOnlyHint annotation by stating that the tool derives P/E and PEG context from the latest close, and it explicitly marks itself as read-only. No contradictions with annotations.

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

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

Three sentences, each providing distinct value: core function, derived context, and read-only designation. No superfluous words; well front-loaded with the main purpose.

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

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

For a tool with 3 parameters and no output schema, the description covers the main return data (estimates, guidance, revisions, derived metrics). It lacks details on pagination or error handling, but these are not critical for basic usage.

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

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

With 100% schema coverage, the description does not need to repeat parameter details but adds context about the type of estimates (revenue, EPS, EBITDA) which relates to the output. It does not provide additional parameter syntax or behavior 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 explicitly states the verb 'Fetch' and the resource 'forward consensus revenue/EPS/EBITDA estimates' for a specific Bullrun ticker, clearly distinguishing it from sibling tools like 'get_earnings_call_transcript' or 'get_financial_history' which cover other data types.

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

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

The description clearly states it is for 'one exact Bullrun ticker', implying it should not be used for multiple tickers or other platforms. However, it does not explicitly exclude alternative uses or mention sibling tools for comparison.

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

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

The annotation declares readOnlyHint: true, and the description repeats 'Read-only'. This is consistent and adds no contradiction. However, beyond that, the description does not disclose additional behavioral traits such as pagination, error handling, or rate limits. Given the annotation covers the safety profile, a score of 3 is appropriate.

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

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

The description is two sentences with no superfluous words. The first sentence conveys the purpose and examples, the second confirms idempotency. Highly efficient.

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

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

Given no output schema, the description lists example metrics, which helps the agent anticipate return values. It also specifies that the ticker must be exact. It does not mention result ordering or pagination limits (though limit parameter exists), but overall it is complete enough for a read-only data retrieval 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%, so the schema already documents all parameters. The description lists example values for ticker, category, and metricKey but does not add significant meaning beyond the schema. The baseline of 3 is correct.

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

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

The description clearly states the tool fetches operating KPIs and unit-economics metrics for a specific ticker, listing concrete examples like ARR, NRR, RPO. This distinguishes it from sibling tools that handle financial history, transcripts, etc.

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 says 'for one exact Bullrun ticker', implying a required ticker. It provides context about period-specific KPIs but does not explicitly state when to use this tool vs. alternatives like get_financial_history or get_forward_estimates. However, the examples differentiate it sufficiently.

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?

Description discloses behavioral traits beyond annotations: risk math drops holdings with insufficient history, coverage banner in response, privacyMode hides USD amounts while keeping weights/scores. No contradiction with readOnlyHint=true.

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

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

Description is comprehensive but somewhat lengthy; every sentence adds value. Front-loaded with use cases. Could be slightly more terse, but no wasted text for a complex tool.

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

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

Given 5 parameters, no output schema, and complex behavior (holding filtering, privacy mode), the description covers all critical aspects: return structure, limitations, alternatives, required inputs, parameter behaviors. Very complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra context: candidateTicker explanation (Bullrun ticker, not Yahoo-style), days default 370, privacyMode default 'full' vs 'weights_only', candidateWeightPct default 5%. Not all parameters need extra detail, but adds value beyond 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 starts with clear use cases (risk, diversification, concentration) and explicitly states the tool fetches portfolio-level analytics. It distinguishes from sibling tool get_portfolio_context, which does plain holdings snapshot.

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

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

Explicitly states when to use (user asks about risk, diversification, adding a stock) and when not (use get_portfolio_context for plain snapshot). Also mentions required portfolioId from list_portfolios and optional candidateTicker for 'should I add' queries.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to reiterate safety. However, it adds critical behavioral context: the response always returns a complete holdings list with matched/unmatched flags, a coverage summary, and warns against presenting matched-only figures as the whole portfolio. This is valuable beyond the annotation.

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

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

The description is somewhat long but well-structured: usage guidance first, followed by response structure details, caveats, and alternative tool reference. Every sentence adds value, though it could be slightly tighter without losing clarity.

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

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

Given no output schema, the description fully explains the return shape (summary, holdings, insights, coverage banner). It also covers privacyMode and clarifies that holdings may lack weight/sector/insight for unmatched items. This is exceptionally complete for a non-trivial 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% (each parameter has a description). The description adds value by explaining portfolioId's origin ('from list_portfolios'), clarifying days as a look-back window, and illustrating privacyMode's effect on output format. This enriches the schema's baseline.

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

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

The description starts with explicit use cases ('Use when the user asks to look at, review, or analyze THEIR portfolio / holdings / positions') and provides concrete example queries. It clearly distinguishes the tool from siblings like get_portfolio_analytics by naming that alternative for risk/diversification analysis.

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

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

The description explicitly states when to use (portfolio review/analysis), when not to use for risk analytics (points to get_portfolio_analytics), and instructs to call list_portfolios first if portfolio ID is unknown. This provides clear decision guidance.

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

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

The annotation readOnlyHint=true already indicates no side effects. The description adds that metrics are computed from 'existing financial statements', implying no new data creation or modification. It lists the specific metrics computed, providing insight into the return content beyond the annotation.

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

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

The description is concise and front-loaded, with the primary purpose in the first sentence. Every sentence contributes value: the first states the overall function and the second lists key metrics. No unnecessary words or repetition.

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

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

Given four well-documented parameters, no output schema, and readOnly annotation, the description covers the tool's purpose and what it computes. It could be more complete by specifying output format (e.g., table or JSON) or data prerequisites (e.g., financial statements must exist). However, the 'existing financial statements' hint partially addresses this.

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

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

Schema description coverage is 100%, with detailed descriptions for each parameter (e.g., ticker includes format guidance and fallback instructions). The tool description adds no additional parameter semantics beyond what the schema already provides. Baseline 3 is appropriate as the description does not enhance parameter understanding.

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

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

The description clearly states the action ('Compute'), the resource ('annual quality, moat, earnings-quality, and capital-allocation metrics'), and the scope ('for one exact Bullrun ticker from existing financial statements'). It lists specific metrics (ROIC, ROE/ROA, etc.), which distinguishes it from sibling tools like get_financial_history or get_stock_metrics. The 'Read-only' tag aligns with the annotation.

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

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

The description implies usage for computing quality and moat metrics from existing financial statements but does not explicitly state when to use this tool versus alternatives such as get_financial_history or get_forward_estimates. No when-not-to-use scenarios or preconditions are mentioned.

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

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

Annotations already declare readOnlyHint=true, and the description confirms 'Read-only.' Beyond that, it adds minimal behavioral context (e.g., no mention of rate limits, pagination, or error handling). The description is adequate but does not significantly enrich behavioral transparency beyond what annotations provide.

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 front-loaded with action and resource, followed by usage guidance and a read-only note. Every sentence adds value with no redundancy.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description covers what, when, and safety. It could mention that return format is an array of rows, but that's implicitly understood from 'rows'. Slightly incomplete but largely sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions the dimension types (segment, geography, etc.) but the schema already defines them via an enum. No additional parameter semantics beyond what the schema provides.

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

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

The verb 'Fetch' and specific resource 'revenue breakdown rows for one exact Bullrun ticker' clearly state the tool's function. It distinguishes from siblings like get_financial_history by focusing on revenue breakdowns and exact ticker-level 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?

Explicitly provides use cases: 'separate cyclical businesses from recurring segments or inspect geographic exposure instead of relying on blended revenue.' This gives strong context for when to use, though it lacks explicit when-not-to-use or alternative tools.

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

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

The description adds value beyond the readOnlyHint annotation by stating it is 'Read-only' and explaining error behavior ('If a ticker returns no data'). However, it does not discuss rate limits or authentication, but given the annotation already covers safety, the additional context is sufficient.

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

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

The description is detailed yet every sentence adds value. It is front-loaded with the main purpose, uses clear enumeration, and avoids redundancy. No unnecessary words.

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

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

Given the tool has one parameter, no output schema, and rich annotations, the description fully covers input, failure behavior, and output data fields. It is complete for an agent to use correctly.

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

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

The single parameter 'ticker' has 100% schema coverage, but the description adds extensive meaning: it specifies the exact format (native local-exchange symbol, examples, prohibited suffixes). This goes well beyond the schema's description.

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

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

The description clearly states it fetches a consolidated metrics snapshot for a single stock by ticker, listing specific data categories (identity, price, valuation, financials, description). It distinguishes from siblings like screen_stocks by focusing on a single stock and providing ticker format guidance.

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

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

The description explicitly says when to use the tool (fetch stock metrics) and when not to ('If a ticker returns no data, use screen_stocks...'). It also provides detailed ticker format instructions, preventing common mistakes like appending Yahoo suffixes.

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

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

Annotations provide readOnlyHint=true, and description adds OAuth requirement, user-specific data limitation, privacyMode behavior, and read-only nature. No contradiction.

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

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

Well-structured with purpose first, then details. Slightly verbose but every sentence adds value. Could be shortened without loss.

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?

Covers all necessary aspects: purpose, prerequisites (OAuth), return value, parameters, privacy mode, and relationship to sibling tools. No output schema needed for this list operation.

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?

Only one parameter (privacyMode) with 100% schema coverage. Description adds context beyond enum values: explains defaults and effect on returned data. Slightly redundant with schema description but clear.

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

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

Description uses specific verb 'list' and resource 'portfolios', explains it returns computed summaries, and distinguishes from siblings by stating 'start here when a portfolio question doesn't name a specific portfolio'.

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

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

Explicitly states when to use (user refers to 'their' portfolios/holdings) with examples. Provides clear context: start here, then pass portfolioId to get_portfolio_context/analytics. Does not mention when not to use or list alternatives, but the guidance is clear.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful context about legacy compatibility and the bundled response for exact tickers. However, it does not mention potential performance implications or error behavior, which would be valuable for a tool intended for older clients.

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

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

The description is succinct and front-loaded with purpose and alternatives. The final 'Read-only' sentence is redundant with the annotations and could be omitted without loss, but the overall structure is tight.

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 13-parameter compatibility tool with no output schema, the description gives the essential context: legacy purpose, search scope, optional bundled data, and modern alternatives. It does not describe response structure or edge cases, but the parameter schema covers the input details thoroughly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail. The description adds some context by explaining the bundling relationship between ticker, prices, and holdings, but this is also hinted at in the individual 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 explicitly states it is a compatibility tool for older clients that searches the Bullrun ETF universe and can bundle profile, prices, and holdings for a ticker. It also distinguishes itself by naming the newer alternative tools.

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

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

It explicitly advises new clients to use search_etfs, get_etf_snapshot, and get_etf_holdings, listing specific benefits of those alternatives (smaller responses, structured output, quantitative filters, explicit coverage metadata). This gives clear when-to-use vs. when-not-to-use guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavioral and operational details: this is 'the heaviest read in the API', metered against a small per-day action budget, and that 'Percentages are percentage points' — clarifying output semantics. This adds real context beyond what annotations alone provide.

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?

Despite describing a 24-parameter tool, the description is compact and front-loaded. Three sentences cover purpose, usage guidance, behavioral caveats, and unit semantics with zero filler or redundancy. Every sentence earns its place.

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

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

Given the tool's complexity, the output schema exists, and the description covers the full screening scope, the differentiation from a sibling tool, rate limiting, and result reporting (evaluatedCount, matchCount). Nothing crucial is missing for an agent to select and invoke this tool effectively.

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 covers 100% of parameters, so the baseline is 3. The description adds value by grouping parameters into mental categories (expense ratio, AUM, yield, etc.) and by clarifying that holdingSearch 'finds funds by what they hold', plus the percentage-points note. This helps an agent quickly understand relationships between the many metrics.

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

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

The description opens with 'Screen the WHOLE ETF universe by numeric rules and fund attributes in one pass', which is a specific verb (screen) plus a clearly defined resource (whole ETF universe). It immediately distinguishes itself from search_etfs by contrasting full-universe evaluation versus a bounded candidate scan.

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

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

Explicit usage guidance is provided: 'Prefer this over search_etfs for any cheapest / largest / best performing / most liquid question' and it names the alternative tool. It also warns against probing repeatedly due to a per-day action budget, giving the agent clear when-to-use and when-to-avoid 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 declare readOnlyHint=true, and the description reinforces this with 'Read-only'. It adds context about using the same rule engine as the app screener and returning a compact table, which is helpful beyond the annotation.

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

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

The description is extremely concise: two sentences that capture the tool's purpose, scope, and result type. Every word adds value, with no redundancy.

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

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

Given the complexity (15 parameters, no output schema), the description provides a solid overview. The schema handles detailed parameter info. It could mention default values or array behavior, but overall it's reasonably complete.

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

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

Schema coverage is 100%, but the description synthesizes the parameters into a coherent narrative (e.g., 'AND/OR rule groups', 'comparison operators', 'money units'). This adds meaning beyond individual parameter descriptions, earning a 4.

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 that the tool screens the Bullrun stock universe using the same rule engine as the app, and lists the many filtering criteria. It distinguishes itself from sibling tools like get_stock_metrics and query_etfs by focusing on screening with complex rule logic.

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 implicitly explains when to use this tool (to filter stocks by various criteria), but does not explicitly contrast with alternatives or state when not to use it. The context is clear enough for an agent to decide, but lacks explicit 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?

Beyond the readOnlyHint annotation, the description discloses a critical behavioral trait: minAum and minYieldTtmPct are applied only to a 'bounded profile-enriched candidate scan', and warns not to describe results as exhaustive when candidateCapReached is true. This prevents misinterpretation of results and goes above and beyond what annotations provide. No contradiction with annotations.

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

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

The description is three sentences, information-dense, and front-loaded with purpose. Every sentence earns its place: purpose/filters, usage guidance with alternatives, and the critical non-exhaustiveness caveat. No wordiness or repetition.

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 an 18-parameter tool with a rich schema and output schema, the description covers the primary use case, differentiates from relevant siblings, explains the main limitation, and directs users to specialized tools. It is complete enough without needing to restate schema content.

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 high (83%), so a baseline of 3 applies. The description adds meaningful parameter context by explaining that minAum and minYieldTtmPct operate on a bounded candidate scan, clarifying their effect. It also maps the search parameter to 'name, ticker or ISIN' and lists filter categories that map to several parameters. This adds value beyond the schema without covering every parameter.

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

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

The description uses a specific verb ('Look up') and identifies the resource (ETFs) plus scope (by name, ticker or ISIN) and filter domains (classification, listing, index, etc.). It explicitly distinguishes from screen_etfs by stating it is 'Best for finding a known fund', and names other sibling tools for different use cases, providing clear differentiation.

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

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

The description gives explicit when-to-use guidance ('Best for finding a known fund'), when-not-to-use ('For ranking questions... prefer screen_etfs'), and prescribes alternative tools ('Use get_etf_snapshot for one listing, get_etf_fund to resolve an ISIN across venues, and get_etf_holdings for constituents'). This is exemplary usage 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?

The readOnlyHint annotation is reinforced by the 'Read-only' statement. The description adds valuable context beyond the annotation by explaining the comparative methodology ('Compares the same gross-return path with and without costs') and describing outputs ('reports direct charges plus ending-value drag'). It also discloses limitations (exclusions). This exceeds the baseline transparency expected from a read-only annotation.

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

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

The description is three sentences long, front-loaded with the core purpose, and every sentence adds value (purpose, methodology, exclusions, read-only note). No fluff or repetition of schema information.

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

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

Given the tool's complexity (9 parameters, output schema, read-only annotation), the description adequately covers the purpose, methodology, and scope. It does not need to explain return values due to the output schema. The main gap is lack of usage alternatives or clarification of edge cases, but the description is largely complete for a simulation tool.

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

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

The schema description coverage is only 44%, and the description does not compensate sufficiently. It lists broad input categories ('expense-ratio, assumed bid/ask spread, commissions, and recurring contributions') but does not add meaningful detail about individual parameters, their interactions, or the meaning of 'ending-value drag'. The schema already describes a few parameters (e.g., spreadPct, expenseRatioPct), so the description adds little beyond a high-level summary.

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

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

The description uses a specific verb ('Simulate') and clearly identifies the resource (ETF cost) and scope ('expense-ratio, assumed bid/ask spread, commissions, and recurring contributions over a holding period'). It also differentiates from sibling tools by emphasizing the comparison of gross-return paths with and without costs, which is unique among the listed getters and portfolio tools.

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

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

The description provides clear context for when to use the tool (to simulate ETF costs over a holding period) and explicitly states exclusions ('Taxes, FX, market impact and brokerage-specific fees are excluded unless represented by the inputs'). However, it does not name alternative tools or explicitly state when NOT to use it, so it falls short of a 5.

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