Bullrun

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

Adds substantial context beyond the read-only annotations: cost profile (one cached graph read per company plus a possible ticker lookup, no paid discovery), evidence statuses (VERIFIED vs SUGGESTED/NEEDS_REVIEW with confidence and sole-source flags), and the critical caveat that missing graphs or edges mean unknown coverage rather than no relationship. That last point is a behavioral trap an agent would otherwise fall into.

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

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

Front-loaded with the core action, then layered with cost and evidence caveats; nearly every sentence carries operational weight. It runs long and includes return-format detail that the output schema already provides, which slightly dilutes focus.

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 a read-only tool with a full output schema and complete parameter descriptions, the definition is essentially complete: it covers cost, coverage gaps, evidence labeling and truncation. The return-shape sentence duplicates the output schema rather than adding new information, leaving only minor room for improvement.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the constraint that only stable entity IDs or exact tickers are accepted and that results are per-input-company, reinforcing the truncation semantics of limitPerCompany. Minor tension: it mentions entity IDs while the schema accepts only tickers, but overall it adds value over the schema.

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

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

States a specific verb and resource: compare the cached relationship graphs of two to five tickers, finding shared suppliers/customers/competitors/partners. This clearly separates it from single-company siblings like get_company_relationships and from compare_stocks/compare_etfs.

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

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

Gives clear context for use (cross-ticker shared counterparty analysis, including cross-role overlaps) and important exclusions: it never starts paid discovery, never infers exposure weights or portfolio losses. It does not explicitly name which sibling to use instead for single-company relationship lookups, so routing against alternatives is left partly implicit.

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

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

Beyond the readOnly/openWorld annotations, the description discloses real behavioral traits: overlap matching by security identity rather than ticker, exclusion of cash/currency/derivatives, missing holdings making overlap unavailable, partial holdings making it a lower bound, and that leaders are mechanical extrema rather than recommendations. These are exactly the caveats an agent needs to interpret results honestly.

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

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

The core purpose is front-loaded in the first sentence and the remaining clauses each carry caveat information. Minor waste: the trailing 'Read-only.' restates the readOnlyHint annotation, and the middle is a dense run of caveat clauses that could be itemized.

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 multi-module comparison tool with an output schema (so return structure needn't be explained), the description covers selection semantics, failure modes, interpretation guidance, and currency/date caveats. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks — identity-based matching, derivative/cash exclusion, and lower-bound behavior for the overlap module and its stored-snapshot basis. It does not expand on performanceDays or topSharedLimit beyond the already-rich schema text.

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

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

States a specific verb and resource ('normalized side-by-side comparison of two to ten ETFs') and enumerates exactly which modules the comparison spans. An agent can distinguish it from single-fund siblings like get_etf_holdings or get_etf_snapshot and from compare_stocks without opening the schema.

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

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

Usage is implied by the comparison framing and the note that 'only requested modules run' and 'overlap alone fetches no price history', which helps with module budgeting. However, it never routes the agent against alternatives — it does not say when to prefer this over get_etf_holdings, screen_etfs, or compare_company_exposures, nor any exclusions or prerequisites.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: annual-only fiscal years, no FX conversion, native reporting currency, reported missing coverage, and no ranking or generated research. Minor gaps remain around volume/rate limits and pagination, but the disclosure is well above baseline.

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 but front-loaded sentences: the capability and response shape come first, then the explicit exclusions. Every clause carries information, though the negation list is packed and could be split for readability. No filler.

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

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

For a two-parameter, read-only comparison tool with an output schema, the description is nearly sufficient: it defines scope, module contents, currency/period handling and exclusions. It stops short of stating anything about response size or ordering across the compared tickers, which an agent might want to know when comparing five names.

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 both `tickers` and `include` are already documented in detail, including ticker format and per-module semantics. The description adds only the ticker count (2-5) and a summary of module contents, which largely restates the schema. Baseline 3 is appropriate when the schema carries the 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 names a specific verb (compare), a bounded resource (two to five stock tickers), and enumerates exactly what the compact response contains (fundamentals, quality, valuation, risk). It also distinguishes itself from nearby siblings like compare_etfs and find_stock_peers by scoping to stock tickers and to a fixed module set.

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 useful negative scoping ('No currency conversion, quarterly-to-annual substitution, buy/sell ranking or generated research'), which implicitly tells the agent when another tool is needed. However, no sibling is named as an alternative and there is no explicit 'use this when you want to compare X across 2-5 names vs. screen_stocks for discovery' guidance, leaving the choice partly to inference.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false): it discloses the OAuth write:drafts scope requirement, free-account availability with daily limits and capacity constraints, and the crucial behavioral trait that the draft never changes live positions but is saved and surfaced under 'Pending AI drafts' for explicit accept/discard. It also bounds ticker selection to Bullrun's priced universe.

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

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

Front-loads the usage trigger and example phrasings before the behavioral details, which is the right ordering. It is on the long side and repeats the draft-only message ('DRAFT-ONLY', 'never changes any live position'), but nearly every sentence carries operational 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?

For a 4-parameter mutation-ish tool with no output schema, the description covers prerequisites, account limits, side effects, where the result appears, and what the user must do next. Nothing an agent needs to invoke it correctly or set expectations is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: tickers come only from Bullrun's priced stock/ETF universe and instrumentUniverse selects stocks-only, ETFs-only, or a mix. It does not add format detail for maxPositions or startingCash beyond what the schema states, keeping it at a 4 rather than a 5.

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

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

States a specific verb and resource ('BUILD or PROPOSE a brand-new portfolio', 'Generates a REVIEWABLE paper-portfolio draft') with example user phrasings. It explicitly distinguishes itself from create_position_draft, which handles additions to an existing portfolio, so an agent can route correctly without opening either schema.

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

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

Provides explicit when-to-use triggers, names the alternative (create_position_draft) and the condition that selects it, and gives concrete guidance for vague briefs (one round of up to three multiple-choice questions with defaults, skip already-specified dimensions).

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

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

Goes well beyond the annotations (readOnly=false, destructive=false, openWorld=false) by disclosing the full lifecycle: draft is saved to the Bullrun account, appears under "Pending AI drafts", requires explicit user acceptance to create a NEW portfolio, and never mutates live positions. It also names the OAuth scope (write:drafts) and the free-tier daily limits and portfolio-capacity constraints.

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

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

Front-loaded with the triggering condition and the sibling contrast, so the most decision-relevant content lands first. It is a dense block of several long clauses (auth scope, draft lifecycle, ticker resolution) that could be split for scanability, but no sentence is filler.

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

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

For a write tool with no output schema, the description covers the important unknowns: what gets created, where it appears, that it is inert until accepted, and that unpriceable tickers come back in `unresolved` and are skipped. It stops short of describing the rest of the successful response (e.g. the draft identifier), which leaves a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents name, cashPct, weights, amounts, and startingCash in detail. The description reinforces the weight-vs-USD sizing choice and adds the universe constraint, but that is largely restatement rather than new parameter meaning — baseline 3 is appropriate when the schema carries the load.

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

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

States a specific verb and resource — persists a reviewable paper-portfolio draft built from tickers the caller supplies — and immediately contrasts it with create_portfolio_draft ("does NOT use the LLM and NEVER re-selects tickers"). An agent can distinguish this from the vague-brief sibling without opening either schema.

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

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

Gives an explicit trigger condition ("when YOU (or the user) have ALREADY decided the exact holdings"), names the counter-case and the alternative tool ("For a vague brief where the model should pick, use create_portfolio_draft instead"), and even routes ticker verification to search_etfs / screen_stocks first.

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

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

Goes well beyond the annotations by disclosing the OAuth scope (write:drafts), free-account availability, daily usage limits, and portfolio capacity constraints. It also defines the write's actual blast radius: drafts land in Pending AI drafts for review and 'never changes live holdings by itself', which resolves the ambiguity left by readOnlyHint=false with destructiveHint=false.

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

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

Front-loaded with the trigger condition and user phrasings before any mechanics, and every later sentence carries a distinct fact (scope, limits, draft semantics, alternatives, clarification rule). It is dense rather than padded, though the length pushes toward the upper bound of what an agent wants to read before a call.

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

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

For a non-destructive write with no output schema, the description covers what an agent needs: auth requirements, quota constraints, where the result surfaces, and that the user must explicitly accept it. Return-value detail is unnecessary because the post-call state is described behaviorally (drafts appear under Pending AI drafts).

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 structured fields already carry the parameter meaning. The description still adds intent mapping the schema lacks: 'a single best idea or a few' ties maxPositions to user phrasing, and 'Pass instrumentUniverse for stocks only, ETFs only, or a mix' frames the enum as a decision an agent must make rather than a raw value list.

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

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

States a specific verb and resource ('Generates REVIEWABLE suggested additions for one existing Bullrun portfolio') with the scope narrowed to additions to an EXISTING portfolio. It explicitly contrasts with create_portfolio_draft and get_portfolio_analytics, so an agent can separate it from the nearest siblings without opening schemas.

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

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

Opens with 'Use when the user asks what to BUY or ADD...' and supplies four concrete user phrasings that trigger it. It names two alternatives with the conditions that select them (whole new portfolio -> create_portfolio_draft; testing a named ticker -> get_portfolio_analytics) and prescribes a single-step clarification flow 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 already cover readOnly/destructive/openWorld, so the bar is lower, yet the description adds real context: deterministic selection order, a scan cap, issuer/listing exclusions, and disclosure of the chosen classification. It stops short of stating result volume or what happens when no industry or sector match exists beyond the matchBy note.

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

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

Front-loaded with the core purpose, then scope, exclusions, and caveats in short declarative sentences. It is dense and jargon-heavy ('Bullrun ticker,' 'scan cap,' 'issuer/listing exclusions') for a four-parameter tool, but nearly every clause carries selection-relevant information.

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

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

With no output schema, the description still says what comes back: compact stored multiples/growth plus compare_stocks arguments. Combined with the coverage of selection order, exclusions, and classification caveats, an agent has enough to call it correctly and interpret results.

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 still adds meaning by framing sameCountryOnly as a preference-with-fallback ordering and matchBy as not widening an empty industry result. The 'compare_stocks supports the subject plus at most four selected peers' note reinforces limit semantics, though it does not restate the 1-10 range.

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

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

States a specific verb and resource: 'Discover stock comparison candidates for one exact Bullrun ticker using stored industry or sector classification.' It is clearly differentiated from the sibling compare_stocks, which it feeds rather than duplicates, and from screen_stocks by being a peer-discovery rather than a filter-scan 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?

Gives explicit boundaries: stored classification only, no generated peers, no paid graph discovery, and peers are 'not verified competitors or a financial-similarity ranking.' It also names the downstream step by saying it returns 'ready-to-use compare_stocks arguments,' which routes the agent to the correct sibling for actual 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?

Although annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, the description adds substantial behavioral context beyond them. It explains what the tool reports, why it exists, and which downstream tools may be subject to account entitlements or usage limits.

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

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

The description is front-loaded with the key instruction: call this before attempting an action. It is dense but mostly purposeful; the entitlement list is useful, though the sentence is long and could be structured as a short list for faster scanning.

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

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

For a zero-parameter, read-only discovery tool with no output schema, the description is complete enough. It explains what is returned in prose and gives the agent a clear operational reason to call it.

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

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

The tool takes zero parameters, so the baseline is 4. There are no parameter names, enums, or formats to clarify in the description.

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

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

The description uses a specific verb and resource: discovering what the connected Bullrun account can do. It clearly enumerates the reported capability categories, including authentication identity, Pro/trial status, OAuth scopes, portfolio usage limits, and per-tool entitlements, making it distinguishable from the sibling 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 gives explicit timing guidance: call this first before attempting an action, especially when a draft/write tool might be gated. It also states an alternate use case: confirming which account a request will act on, which directly maps to real agent workflows.

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/openWorldHint=false, but the description adds genuinely new behavioral context: it is cheap, it does not trigger enrichment, availability is not completeness or accuracy, a null timestamp means freshness is unknown, and a reporting period is not an ingestion date. These caveats directly prevent misinterpretation of the returned manifest.

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

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

Front-loaded with the resource and its contents, then the usage rule, then caveats. No sentence is filler — each clause either scopes the tool or prevents a specific misreading of its output.

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

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

With no output schema, the description carries the burden of describing returns and does so (datasets, periods, timestamps, graph status), plus it flags freshness/accuracy caveats. Nothing an agent needs to invoke it correctly or interpret results is missing.

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

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

Schema description coverage is 100% and the single ticker parameter is documented in extensive detail (examples, suffix behavior, fallback advice) in the schema itself. The description adds nothing about the ticker beyond 'one exact company', so baseline 3 applies.

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

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

States a specific verb and resource ('cheap stored-data manifest for one exact company') and enumerates exactly what it returns: available datasets, latest reporting periods, ingestion/computation timestamps, cached relationship graph status. It also explicitly delineates itself from deeper research endpoints, so an agent can distinguish it from siblings like get_stock_metrics or get_company_relationships.

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

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

'Call before deeper research when coverage or freshness is uncertain' gives a clear triggering condition, and 'never starts enrichment' plus 'reads indexed metadata, not every research endpoint' bound the scope. It stops short of naming specific alternative tools, which keeps it below a 5.

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

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

Goes well beyond the annotations by disclosing a real side effect the annotations only imply via readOnlyHint=false: reading news registers demand and triggers a best-effort background refresh that the response does not wait for or confirm. It also bounds the search scope (only newest 50 stored articles) and states the tool does not modify portfolios or place trades, which is exactly the kind of context an agent needs before treating stale output as truth.

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

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

Front-loaded with purpose, scope and ordering, then alternatives, then behavioral caveats. It is dense and long-ish, but every sentence carries operational information (ordering, 50-article cap, refresh behavior, no-write guarantee), with no filler.

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

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

With no output schema, the description still enumerates the returned fields including stored-fetch freshness, and it explains best-effort refresh behavior and the limits of cached/empty results. Nothing an agent needs to call it correctly or interpret an empty response is missing.

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

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

Schema description coverage is 100%, so ticker syntax, since cutoff semantics and the limit cap are already fully documented in the schema; the description mostly restates 'since cutoff and limit up to 50'. Baseline 3 applies since the schema carries the parameter burden.

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

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

States a specific verb and resource ('cached company news for one exact Bullrun ticker') plus ordering ('newest publication first') and returned fields (publisher, source URL, date, freshness). It explicitly separates itself from get_corporate_calendar and get_earnings_call_transcript, so an agent can route correctly without opening any schema.

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

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

Gives an explicit positive use case ('company headlines and article sources') and names two alternatives with the conditions that select them (scheduled earnings/dividends vs. call text). When-not guidance is also present: cached/empty/stale results do not prove absence of new events.

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

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

Beyond the read-only annotation, the description discloses that the tool returns only the cached graph and never starts a paid discovery run, that a company with no graph reports status 'none', and that a missing edge is not proof of no relationship. It also explains verification statuses, confidence, sole-source flags, and quantified dependence evidence, giving the agent important behavioral context.

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

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

The description is front-loaded with the resource and returned fields, then moves to use cases, follow-on calls, caching behavior, and caveats. Despite its length, every sentence adds useful context and there is no obvious filler.

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

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

With no output schema, the description sufficiently explains what the graph contains, including relationship roles, tickers, verification status, confidence, dependence metrics, and evidence. It also covers caching behavior, missing-data caveats, and safety context, so an agent has enough information to call and interpret the tool.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters in detail, including the roles enum, evidence modes, limitPerRole, and verifiedOnly. The description reinforces the role categories and verification/evidence concepts but does not add parameter-level semantics beyond what the schema already 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 description clearly states the resource: Bullrun's company relationship graph for one stock, enumerating competitors, suppliers, customers and partners and the fields returned. It is specific, but it does not explicitly contrast this tool with close siblings such as find_stock_peers or compare_company_exposures; it only names follow-on tools like get_company_risk and get_stock_metrics.

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 provides explicit use cases ('who supplies X', 'who depends on X', 'who competes with X', second-order risk) and names follow-on tools to call on counterparties. It also discloses the cached-only limitation and the 'missing edge is not proof' caveat, but it does not explicitly say when not to use this versus a sibling like find_stock_peers.

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, destructiveHint=false, openWorldHint=false, so safety is covered; the description adds real non-annotation context: dials have a direction versus the prior reading, risk factors are filing-derived (10-K/annual report), and bands measure strain rather than a buy/sell recommendation. It does not discuss latency, coverage gaps, or what happens when a module has no data, which would be needed for a 5.

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

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

Effectively one long front-loaded sentence plus three short follow-ups; the core purpose and return contents come first and nothing is wasted. The opening sentence is dense with parenthetical enumerations that could be tightened, costing it the top score.

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 complex, no-output-schema, five-parameter analytics tool the description does the heavy lifting: it names every returned module, the band vocabulary, and the severity/mechanism metadata on risk factors. Missing only edge-case behavior (empty modules, ticker ambiguity handling), which the ticker schema partly covers.

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

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

Schema coverage is 100% and each parameter already carries a thorough description, including ticker resolution rules and per-module meanings for 'include'. The prose adds no parameter-level guidance beyond restating the module set, so the baseline 3 applies.

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

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

Opens with a specific verb and resource ('company risk read for one stock') and immediately enumerates the concrete outputs: a 0-100 composite score plus six named mechanism dials with bands, direction, driver and explanation. It is clearly distinguishable from siblings like get_etf_risk, get_risk_movers and get_company_risk_history, none of which are described as a per-stock composite with mechanism dials.

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

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

Gives concrete trigger phrasings ('how risky is X', 'is X's supply chain concentrated') and a workflow cue ('before adding a stock to a portfolio'), plus an explicit pairing instruction with get_company_relationships. It lacks an explicit when-not-to-use clause (e.g. versus get_company_risk_history for trend-only questions), which keeps it below a 5.

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

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

With annotations already covering read-only and closed-world, the description still adds substantive semantics: missing history means unknown rather than zero risk, gaps and retention vary, scores are not proof of causation. These are interpretation rules an agent cannot get from the annotations or schema.

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

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

Front-loaded with what is returned, then usage, then caveats, then safety in four dense sentences. The mid-sentence enumeration ('changing input coverage and measurement bases') is slightly packed but every sentence carries information.

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

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

There is no output schema, so the description carries the burden of describing results, and it does: dates, computation times, formula versions, score changes, changed inputs. Combined with the missing-data caveat, an agent knows enough to call and interpret it correctly.

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

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

Schema coverage is 100% and the schema already explains limit (latest stored run dates, max 30), detail (summary vs full), and ticker formats. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Stored historical company risk category readings and their observed input changes') and enumerates what the payload contains (dates, computation times, formula versions, score changes). It distinguishes itself from the current-state and timeseries siblings by explicitly saying these are retained category scores, not a complete daily series.

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?

Names the exact user questions this answers ('how has X's risk changed?', 'which inputs changed?') and gives an exclusion ('does not run risk computation or paid discovery'). It stops short of naming the alternatives, e.g. get_company_risk for the current reading or get_risk_movers for cross-company movers, so routing between siblings still requires inference.

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

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

Goes well beyond the annotations by disclosing partial coverage, that missing events mean unknown coverage rather than absence, that dates and estimates change, that q silently widens earnings/ex-dividend to 120 days and listings to 60 months, and a request budget of at most three calendar requests plus a ticker lookup. These are real behavioral traits an agent cannot get from the schema.

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

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

Dense but front-loaded: purpose first, then caveats, then the request budget. Every sentence carries signal, though the closing sentence about three calendar requests and the Yahoo suffix lookup is compressed to the point of being hard to parse.

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

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

With an output schema present and full parameter descriptions, the description covers coverage limits, data volatility, and read-only safety. A brief note on how the three calendars interleave in the response would close the remaining gap, but nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter interaction context (search widening effective windows, native listing quote currencies, source metadata) that the schema does not state. The q-overrides-days behavior is repeated from the schema, but the surrounding effects are additive.

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

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

The opening sentence names a specific verb and resource: reading stored upcoming earnings, ex-dividend dates, and recent listings. Scope is clear enough that an agent can tell it apart from price-history or estimates tools. It does not explicitly name the nearest sibling (get_forward_estimates) as an alternative.

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

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

States the tool is read-only and clarifies that listings are not an IPO schedule, which implies when the data is appropriate. However, there is no explicit when-to-use versus alternatives such as get_forward_estimates or get_company_data_coverage, leaving selection to inference.

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

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

Annotations already carry readOnlyHint/openWorldHint/destructiveHint, yet the description adds genuine behavioral context beyond them: what the score means and its direction (higher = more stress), which upstream sources feed it (OECD, IMF, BIS, World Bank, Eurostat), and a failure-mode guarantee that thinly covered countries return state "insufficient" rather than a misleadingly calm score. That last point is exactly the kind of non-obvious trait an agent needs before interpreting a result.

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

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

The lead clause is front-loaded on the resource and the stress score, and the closing sentence about the insufficient state is well placed. The long mid-sentence enumeration of all eighteen constituent indicators is dense and could be compressed to pillar names alone without losing routing value, which keeps it from a 5.

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

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

With no output schema, the description carries the full burden of describing returns and does so thoroughly: latest value, period, source, per-input stress contribution, and a historyCode for follow-up calls, all scoped to the six pillars. An agent knows both what it gets back and how to continue into get_macro_history.

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

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

There is a single required parameter with 100% schema description coverage, and the schema already documents alias handling (US, UK, Korea, Eurozone, Euro Area). The description adds nothing about the country argument itself, so this sits at the baseline where the schema does all the work.

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

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

States a specific resource (a single country's macro dashboard from the Global Markets warehouse) and defines the core artifact precisely: a 0-100 stress score with explicit directionality and six named pillars. It also distinguishes itself from the sibling get_macro_history by naming the historyCode field that feeds it, so an agent can route without opening either schema.

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

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

Gives concrete triggering questions ("how is the German economy doing", "is there a housing bubble in Canada", "macro risks in Italy") plus a use case (judging a country backdrop for stocks), which is unusually actionable. It hints at the get_macro_history relationship but never states the inverse exclusion or how it differs from get_macro_indicators, so the routing guidance is clear but not exhaustive.

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 annotations, it discloses important behavior: cached/imported data, a 24-hour cooldown, possibly empty first reads, variable source and publication lag, retained speaker names and paragraph order, and potentially missing roles or section labels. It also explicitly states that portfolios and user data are not changed, which clarifies the read-only intent despite readOnlyHint=false.

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

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

The purpose is front-loaded in the first sentence, followed by compact caveats about import behavior, data freshness, and output limitations. Every sentence adds useful context and there is no filler.

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

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

With no output schema, the description does enough to set expectations about returned transcript paragraphs, speaker names, paragraph order, and missing section labels. It could more explicitly describe the return shape or pagination behavior, but it is otherwise complete for a cached transcript read tool.

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

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

Schema coverage is 100%, so all six parameters are already documented in the input schema with descriptions and bounds. The description only restates that fiscal period and search text are optional filters and does not add syntax or selection guidance beyond the schema, so the 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 opens with a specific verb and resource: 'Read cached earnings-call paragraphs for one exact Bullrun ticker,' and immediately clarifies optional fiscal-period and search-text filtering. This is precise enough for an agent to distinguish it from portfolio, stock-metrics, and other sibling 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 gives useful usage context: the tool reads cached data, a background import may populate up to two recent calls, and the first read may be empty due to a 24-hour cooldown. It does not explicitly name alternatives or when not to use it, but no sibling transcript tool is present, so the missing exclusion guidance is minor.

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 is unusually rich on behavior beyond the annotations: data provenance (provider holdings file vs. Bullrun instrument resolution by ISIN/symbol+name), fallback rules, exclusions (country excludes cash and derivatives), and unclassified handling. However, it omits how the resolution fallbacks affect the 'Unclassified / Not reported' bucket and gives no sense of freshness/staleness of 'latest stored' holdings, so a 3 rather than 5.

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

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

Purpose is front-loaded, but the text is dense and repetitive — two separate sentences begin 'Coverage states...' — and the trailing 'Read-only.' merely restates readOnlyHint=true. Most sentences do carry real information, but the passage would read better tightened.

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 an output schema, no return-value prose is required, and the description covers what an agent needs: sources, fallbacks, exclusions, unclassified semantics, coverage caveats that prevent misreading partial top-holdings data as full exposure, and the unsupported factor/thematic types.

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

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

With schema coverage at 33% (only `ticker` documented in-schema), the description compensates well: it explains what each `types` value yields and how each is derived, and it explains that coverage reports 'any buckets omitted by limitPerType.' The ticker's exact-listing requirement is left to the schema, which already covers it.

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

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

States a specific verb and resource: 'Calculate sector, country, currency, and broad asset exposure from the latest stored ETF holdings.' An agent can tell this is the derived-exposure view rather than the raw holdings (get_etf_holdings), though no sibling is named explicitly to sharpen the boundary.

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

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

It usefully rules out factor and thematic look-through ('unavailable until dedicated source data exists'), steering the agent away from invalid `types` values. But there is no explicit guidance on when to pick this over get_etf_holdings, get_etf_risk, or compare_etfs, and no stated prerequisites.

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

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

Annotations already establish read-only safety, but the description adds important behavioral context beyond them: filter matching is exact, wrong guesses fail silently as zero results, and long-tail facets should be requested explicitly. That directly affects how an agent should sequence calls.

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, front-loaded with what the tool returns and why it matters. Every clause earns its place by naming consumers, failure mode, and call-order guidance.

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

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

With an output schema present and full schema coverage, the description need not detail return values. It supplies the critical operational context: exact matching, zero-row failure mode, and when to call it before search_etfs or screen_etfs.

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 explains limit, facets, and search in detail. The description reinforces the facet categories and notes that issuers and focus strings are long tails, but it does not add syntax or constraints beyond the structured 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 uses a specific verb and resource: list exact values accepted by categorical filters on search_etfs and screen_etfs. It clearly distinguishes this metadata-listing tool from the sibling search and screening tools that consume those values.

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 guidance: call this first whenever a filter value is not already known to be valid. It also explains why by noting exact-match filtering means guessed strings return zero rows and can be mistaken for no such ETF existing.

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/openWorldHint/destructiveHint, so the bar is lower; the description still adds real context by spelling out the resolution path (ticker → fund ISIN) and the unit convention 'Ratios are percentage points.' The trailing 'Read-only' restates the annotation and earns nothing.

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 key differentiator ('Resolve one FUND rather than one listing') is front-loaded, and the remaining sentences move from inputs to outputs to use cases with little waste. The final 'Read-only' is redundant filler against the annotations.

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

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

An output schema exists and the input schema is fully described, so nothing more is required; the description still previews the payload shape, which helps an agent choose this tool over the ETF snapshot/search siblings. Complete for a read-only lookup.

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 both parameters (isin, ticker) are already documented with examples in the schema. The description's 'any venue ticker of the fund' and 'or any venue ticker' framing slightly reinforces the either/or input but adds no format or constraint detail beyond the schema.

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

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

States a specific verb and resource — resolve a FUND (not a listing) from an ISIN or venue ticker — and enumerates exactly what comes back: identity, costs, index, distribution policy, wrapper type, and all venue listings with exchange and currency. That distinction from listing-level siblings (get_etf_snapshot, get_etf_holdings) is made explicit in the first sentence.

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

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

Gives three concrete trigger conditions (user quotes an ISIN, asks which ticker to buy on their exchange, or several tickers may be the same fund), which is genuinely actionable routing guidance. It does not name alternative tools or state when this is the wrong choice.

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

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

Annotations already declare read-only and closed-world, but the description adds meaningful context beyond them: data is a stored snapshot (not live), pagination is cursor-based, the response exposes provider count vs stored count vs covered weight, and isComplete=false/null means partial coverage. The only omission is any mention of freshness or staleness of the stored snapshot.

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 short sentences, front-loaded with what the tool returns. The future-feature sentence about historical as-of selection earns its place by preempting a likely agent assumption, though it could be trimmed slightly.

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

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

With an output schema present the description needn't enumerate return fields, yet it usefully summarizes the completeness signals an agent must interpret. Combined with 100% schema coverage and read-only annotations, an agent has enough to call it correctly; only explicit sibling routing for historical/exposure use cases is missing.

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

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

Schema description coverage is 100%, so ticker, limit, and cursor are fully documented in the schema itself. The description reinforces cursor pagination ('opaque cursor pagination') but adds no format or syntax detail beyond what the schema already provides, so baseline 3 applies.

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

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

The description gives a specific verb and resource — 'Return the latest stored ETF holdings snapshot' — and the word 'stored' plus 'snapshot' signals this is a persisted holding list rather than the exposure/aggregate views offered by siblings like get_etf_exposures or get_etf_snapshot. It stops short of explicitly contrasting itself with those siblings, so an agent must infer the distinction.

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?

'Treat isComplete=false or null as partial look-through data' and the note that historical as-of selection is not yet available give real usage context. However, there is no explicit statement of when to choose this over get_etf_exposures or get_etf_fund, which are the closest alternatives in the sibling list.

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

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

Goes well beyond the readOnlyHint annotation by disclosing ordering (cheapest fee first), fund-level deduplication, the listingCount/venues payload, the UCITS-by-default scope, and the data-quality caveat that funds with no published fee are counted and named. This is exactly the kind of caveat that prevents an agent from overclaiming "cheapest". Minor gap: no pagination/limit behavior described in prose, though limit is schema-documented.

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

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

Front-loads the disambiguating question and the core result shape, and every sentence carries information (ordering, dedup, defaults, fee-omission caveat). Some sentences are long and packed with parentheticals, slightly reducing scanability, but there is no filler.

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

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

An output schema exists, so return values need not be enumerated; the description still supplies the crucial shape (fund-level rows, listingCount, venues, fee-omission count) and the default scope behavior. Nothing an agent needs to call this correctly or interpret results honestly is missing.

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

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

Schema description coverage is 100%, so the schema already explains limit, scope, currency, exchange, indexKey, and distributionPolicy thoroughly (including the SW example for Swiss investors and the SP500/MSCI_WORLD key format). The description only restates the indexKey-omission behavior and defaults, adding no syntax or semantics the schema lacks. Baseline 3 applies.

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

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

States a specific verb and resource (returns every fund tracking one index) plus the exact question it answers, and distinguishes itself from listing-level siblings by emphasizing dedup to one row per FUND rather than per venue listing. An agent can tell this apart from compare_etfs, screen_etfs, or get_etf_fund without opening the schema.

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

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

Gives a clear triggering question ("what is the cheapest way to track <index>?") and the indexKey-omission path for discovery, plus the default scope caveat. It does not explicitly name alternatives such as simulate_etf_cost for total-cost analysis or compare_etfs for multi-fund comparison, so the exclusion guidance is implicit rather than stated.

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

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

Annotations already cover the safety profile, so the description clears the lower bar by adding a substantive methodological caveat: results are price-return risk, not distribution-adjusted total-return risk. It also grounds the computation in 'stored daily close prices' and notes alignment on dates for benchmark metrics. 'Read-only' merely repeats the annotation, which is minor waste rather than a problem.

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

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

Three tight sentences, front-loaded with the primary computation and then the benchmark extension. The trailing 'Read-only' duplicates the readOnlyHint annotation and could be dropped, but overall there is little 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?

With an output schema present, return-value explanation is unnecessary, and the description covers inputs' effect, methodology basis, and a key interpretation caveat. It stops short of noting limits of the lookback window or what happens with insufficient history, but it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so every parameter is already documented (days as calendar-day lookback, riskFreeRatePct as annual percentage points, benchmarkTicker's metric set). The description's only addition is 'on aligned dates' for the benchmark path, which is marginal. Baseline 3 is appropriate given the schema does the heavy lifting.

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

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

Opens with a specific verb (Calculate) and names the exact resource and metric set: drawdown, volatility, VaR, Sharpe, Sortino, Calmar. It also distinguishes the benchmark-enabled mode from the base mode, so an agent can tell this apart from sibling tools like get_etf_snapshot or get_company_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 only conditional guidance is 'With benchmarkTicker, also calculates...', which is really parameter behavior rather than tool selection. There is no statement of when to prefer this over compare_etfs, get_etf_timeseries, or get_portfolio_analytics, and no preconditions (e.g., minimum history) are given.

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

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

Annotations already cover read-only/non-destructive/closed-world, yet the description adds genuinely new behavior: unrequested modules are omitted while requested-but-unavailable modules are named explicitly, and ratios are reported in percentage points. The closing "Read-only." merely restates readOnlyHint=true, so it earns no credit and slightly dilutes the value.

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 short sentences, front-loaded with the core action and scope, and each sentence adds a distinct fact except the trailing "Read-only." which duplicates the annotation. Slight redundancy keeps it just below the top mark.

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

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

For a two-parameter read tool with an output schema, full schema coverage, and annotations covering safety and openness, the description supplies everything else needed: scope, module semantics, omission/availability behavior, and unit conventions for the returned numbers.

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 goes beyond it by explaining the include array as a fetch-and-return filter and by stating the percentage-point unit convention, which is data semantics the schema does not carry. Ticker precision is left entirely to the schema example, which is acceptable.

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?

"Fetch a modular snapshot for one exact ETF listing" gives a specific verb and resource, and the word "modular" plus the module list distinguishes it from bulk/comparison siblings. It stops short of naming the adjacent single-ETF siblings (get_etf_fund, get_etf_holdings, get_etf_risk) that an agent would need to choose between.

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

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

Usage is implied by "one exact ETF listing" (single-entity lookup, not screening/comparison), but there is no explicit when-to-use or when-not-to-use guidance and no alternative named among the many ETF siblings. An agent can infer a rough fit but must still reason about overlap with get_etf_fund and get_etf_exposures.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description still adds real behavioral value: unavailable requested series are named in unavailableSeries and are never silently approximated with price returns, and series availability has prerequisites. Return shape details (e.g. unavailableSeries structure) are left to the output schema.

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

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

Two dense sentences, front-loaded with the core capability followed by the availability caveat. The trailing 'Read-only.' merely restates the readOnlyHint annotation and is the one sentence that does not earn 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?

For a read-only fetch with an output schema (so return values need no prose) and explicit child-series caveats, this is nearly complete. Minor omission is how limit interacts with interval aggregation and date filtering, which matters for a 7-parameter tool.

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

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

With 57% schema coverage, the description compensates for the weakest spots: it explains that benchmark requires an explicit priced benchmarkTicker because a benchmark name cannot resolve to a price series, and it clarifies series availability semantics. It says nothing about how limit interacts with interval aggregation or about startDate/endDate beyond their pattern, leaving gaps.

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

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

States a specific verb and resource ('Fetch ETF price or price-return history') plus the supported intervals, which immediately separates it from snapshot/exposure siblings. It never names a sibling such as get_etf_snapshot or get_stock_price_history to draw the boundary explicitly, so it stops short of a 5.

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

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

Usage is implied by the name and the series/interval framing, and the description does explain the conditional rule that NAV/total-return/benchmark series only appear when source data or an explicit benchmarkTicker exists. However, it gives no when-to-use vs when-not guidance and never points to an alternative tool.

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 this is a read-only, non-destructive, closed-world operation. The description adds useful behavioral context beyond that: five-fiscal-year default, years range 1-15, periodType quarterly/both options, ordering of growth checks, and source-currency coverage caveat. Pagination and rate-limit behavior remain unstated.

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

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

Two well-formed sentences, front-loaded with the primary action and scope, then defaults and usage. The dense list of statement areas is purposeful and no sentence is wasted.

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

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

With no output schema, the description carries more of the burden and does a solid job outlining the returned statement categories, defaults, period options, and currency coverage. Some response-shape details remain implicit, but an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all four parameters in detail. The description reinforces ticker exactness and mentions years=1-15 and periodType behavior, but it adds little semantic detail beyond the schema's own 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?

States a specific verb and resource ('Read historical financial statements') and adds scope: one exact Bullrun ticker, growth/CAGR checks, income, balance sheet, cash flow, per-share metrics, margins, and source currency. The purpose is clear, but it does not explicitly name or distinguish itself from close siblings such as get_stock_metrics or get_company_data_coverage.

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

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

Gives concrete usage guidance ('Use for growth consistency, margins, leverage and cash-flow quality') and a practical caveat to check period/currency coverage before comparing. It lacks explicit when-not-to-use guidance or named alternatives, so it falls short of the top score.

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

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

Despite annotations being present, the description adds substantial behavior context: a free on-demand background refresh stores at most one snapshot per day, the first read may be empty, fiscal periods and source currency are preserved, forward P/E/PEG only applies when quote and EPS currency units match, and the tool does not modify portfolios or user data. This also explains the readOnlyHint=false annotation via the snapshot-writing refresh.

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

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

Front-loaded with the core read operation and kept to four dense sentences, each carrying distinct information (data scope, refresh/staleness, gaps, currency caveat). Slightly over-packed with niche P/E/PEG currency detail, but no sentence is pure filler.

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

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

With no output schema, the description does outline the returned content (revenue/EPS estimates, EPS revision percentages, preserved fiscal periods and currency) and warns of empty first reads. It stops short of describing row structure or how annual vs quarterly rows are shaped, but is sufficient to call correctly.

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

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

Schema coverage is 100% and the ticker format caveats (suffixed vs bare codes, resolving ambiguous listings) live in the schema itself, so the schema already does the heavy lifting for all three parameters. The description reinforces the 'exact ticker' constraint and period/currency preservation but adds no syntax or constraint detail beyond the schema, matching the baseline for full 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?

States a specific verb and resource (read cached Yahoo analyst consensus revenue/EPS estimates plus EPS revision percentages) scoped to one exact Bullrun ticker, and explicitly bounds the coverage (no EBITDA, management guidance, or revenue revisions). This distinguishes it from generic fundamentals/valuation siblings without ambiguity.

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

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

Usage is implied by the resource scope ('one exact Bullrun ticker') and the note that the first read may be empty, but the description never names alternatives such as get_financial_history or get_valuation_model, nor when to prefer this tool over them. The reader must infer routing from the sibling list.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, so the 'Read-only' tail is partly redundant. Beyond that, the description adds real behavioral context: daily closes with live intraday index levels while markets are open, per-row historyCode for follow-up calls, and the default section set. It does not discuss size/latency of returning everything, which is the main behavioral risk here.

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

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

Front-loaded with the core claim, then the payload inventory, then use cases and freshness. The opening sentence is very long with embedded parenthetical tickers, but every clause conveys coverage information an agent needs to pick this over a narrower sibling.

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

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

With no output schema, the description must carry the return-value burden, and it does: it names what each of the nine sections contains and the data freshness. Nothing essential for correct invocation is missing given the 0-required-parameter, all-defaults schema.

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

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

Schema description coverage is 100% and the `sections` enum is documented in more detail in the schema than in the description, so the schema carries the burden. The description restates the section families and the default omission of news/us_housing, which is mildly useful but largely duplicative; baseline 3 applies.

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

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

The description states a specific verb+resource ('Bullrun's Global Markets dashboard in one call') and then enumerates the exact contents — indices, policy rates, 16 sovereign yields, 20 FX pairs, commodities, macro tiles, calendar, news, housing. This is clearly distinguishable from siblings like get_macro_indicators, get_macro_history, or get_country_macro, which each cover a single slice.

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

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

It gives concrete trigger phrases ('how are markets doing today', 'what's the macro backdrop', 'what's on the calendar this week', morning briefing) and routes drill-down to get_macro_history via the per-row historyCode. No explicit 'when not to use' for the narrow indicator tools, but the 'in one call' framing implies the breadth tradeoff.

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 / destructiveHint=false, so safety needs no restating; the description instead adds real behavioral context: data can be decades long, output is summary statistics (latest, 1M/3M/1Y/5Y change, range, percentile position) plus resampled points. It does not cover failure modes (e.g., unknown code, conflicting address modes) or date defaults, keeping it below 5.

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

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

Front-loaded with the resource and scope, then addressing modes, then return shape, then use cases — a sensible order with no filler sentences. The long comma-separated series enumeration is informative but dense; it slightly crowds the paragraph.

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

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

With no output schema, the description carries the return-value burden and does so (summary stats + resampled points). Combined with a fully documented 8-parameter schema, an agent has enough to call it correctly; only edge-case behavior (default date window, conflicting address params, unknown series) is left unspecified.

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 3 is the floor; the description earns above that by explaining the three mutually alternative addressing modes (code vs. instrument vs. indicator+country) and by pointing to the sibling tools whose historyCode values the `code` param accepts. It does not disambiguate precedence if more than one address mode is supplied.

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

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

Opens with a concrete verb+resource ('Historical time series behind the Global Markets dashboard') and enumerates the exact data families covered (policy rates, 10Y yields, FX, commodities, VIX, DXY, 2s10s, per-country macro). It is clearly separable from siblings like get_global_markets_overview and get_macro_indicators, which it names as upstream code sources.

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

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

Gives three concrete routing rules for addressing a series (historyCode from a named sibling, instrument name, or indicator+country) plus example questions ('how have rates moved since 2022', 'plot Brent over 10 years'). It stops short of explicit when-not-to-use/exclusion guidance versus the snapshot-style siblings, so it lands at a strong 4 rather than 5.

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

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

Annotations already carry readOnlyHint/destructiveHint, so the appended "Read-only" adds nothing. What does add value is the disclosed row shape (value, period, source, historyCode), which is essential since there is no output schema, plus the coverage ceiling of ~200 countries. Pagination/limit behavior is not 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?

Front-loaded with the core action and scope before the examples, and the closing sentences about row contents and historyCode each earn their place. The long parenthetical indicator list duplicates the enum and inflates the opening sentence, though it does supply natural-language gloss on indicator names.

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

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

With no output schema, the description compensates by naming the returned fields and the historyCode handoff, and it covers all indicator choices. The remaining gap is the limit/pagination parameter, whose default and ceiling are never mentioned in prose, which matters for an agent ranking across ~200 countries.

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 75%; indicator and countries are described in both schema and prose, and the description glosses several enum members more richly than the schema ("real house-price growth", "BIS credit-to-GDP gap", macro_stress as a Bullrun composite). However the limit parameter has no description anywhere, and the description's "up to ~200 countries" conflicts with the schema's max of 250 without explaining the default of 25.

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

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

States a specific verb and resource — cross-country macro comparison from Bullrun's warehouse, ranking up to ~200 countries on one indicator — and enumerates the indicators so the agent knows the exact scope. The concrete query examples ("fastest growing economies", "highest inflation in Europe") make it unmistakable against siblings like get_country_macro or get_global_markets_overview.

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

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

Usage is well signalled: the two modes (rank all countries vs. compare a named set) are described, and the user-phrase examples anchor when to reach for it. The handoff to get_macro_history via historyCode is explicit. It stops short of naming the sibling that covers the single-country case (get_country_macro), leaving that boundary to inference.

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

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

Adds substantial context beyond the readOnlyHint/openWorldHint annotations: coverage is sparse, no automated KPI feed exists, and results carry stored fiscal periods, units and source links. The trailing 'Read-only' merely repeats the annotation, and nothing is said about ordering or empty-result behavior, so it stops short of a 5.

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

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

Four short sentences, front-loaded with the operation, then the sparse-coverage caveat, then the prerequisite, then return shape. Only the redundant 'Read-only' tail fails to earn 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?

With no output schema, the description does the work of describing returns (fiscal periods, units, source links) and sets expectations about sparse coverage and the separate company-economics dataset. Complete enough to call correctly; only minor gaps like empty-result handling 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%, so ticker format, category, metricKey and limit are already fully documented in the schema. The description reinforces the ticker exactness requirement but adds no new syntax or constraint information beyond that; baseline 3 applies.

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

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

States a specific verb and resource ('Read curated, source-linked operating KPI observations') scoped to 'one exact Bullrun ticker', and explicitly separates itself from the 'company-economics observations' dataset. An agent can distinguish it from siblings like get_revenue_breakdown or get_financial_history without opening a schema.

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

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

Explicitly routes the agent: 'Check get_company_data_coverage first', plus a clear when-NOT clause ('do not assume ARR, retention, customer counts or payments metrics are available'). It names both the prerequisite tool and the excluded dataset, leaving little inference.

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

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

Annotations already declare readOnlyHint/no-destructive, yet the description adds substantial context beyond them: OAuth scope read:portfolios, caller-scoped data only, exclusion of holdings without sufficient price history plus renormalization, look-through coverage computed independently from the risk-history subset, partial ETF snapshots yielding a lower bound, and a directive to surface the coverage banner. It also discloses the privacyMode effect on absolute USD amounts.

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

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

Front-loaded with purpose and alternatives before diving into the coverage caveats, and every sentence carries actionable information. It is dense and reads as a long run-on chain, which slightly slows scanning for an agent parsing it quickly.

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 six-parameter analytics tool with no output schema, the description covers auth, caller scoping, privacy modes, conditional parameters, output field naming (lookThroughFit), and the critical coverage-caveat behavior. An agent has everything needed to call it and to report results honestly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantic linkage the schema does not state: which parameters drive correlation/pro-forma volatility, that look-through results appear in lookThroughFit with separate coverage/warnings, and that look-through coverage is independent of the risk-history subset. Minor gap: it does not explain the days lookback window semantics beyond what the schema already documents.

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

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

Opens with a specific verb and a concrete resource set (risk, diversification, concentration, candidate stock/ETF analytics) and enumerates the outputs (correlation/covariance, risk contributions, exposures, stress scenarios). It also explicitly names the sibling it is not (get_portfolio_context for holdings/value), so an agent can route without opening either schema.

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

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

Gives explicit when-to-use routing (portfolioId from list_portfolios, get_portfolio_context for holdings/value and coverage), conditional parameter guidance ('Set candidateTicker for correlation and pro-forma volatility', 'add includeLookThrough=true for direct/ETF underlying overlap'), and the prerequisite dependency (includeLookThrough requires candidateTicker). Nothing is left to inference.

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

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

Goes well beyond the readOnly/destructive/openWorld annotations: it discloses the OAuth scope (read:portfolios), the caller's-own-data restriction, the privacyMode default and its effect on returned figures, and a non-obvious data-quality behavior — unmatched holdings carry no weight/sector/insight so aggregate figures describe only the matched subset, with an instruction to read the coverage banner and never present matched-only numbers as the whole portfolio.

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

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

Front-loaded with the trigger condition and dense throughout — nearly every sentence carries either a routing rule or a data-integrity warning. It is a long single block, and the privacyMode/portfolioId restatements duplicate the schema, which is the only thing keeping it from a 5.

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

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

With no output schema, the description carries the burden and does so fully: it lists the response sections, flags the matched/unmatched coverage caveat and banner, states auth requirements and the privacy default, and points to the sibling for analytics. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented in structured fields. The description largely restates what the schema says (portfolioId as returned by list_portfolios, privacyMode full vs weights_only) and never mentions `days` or its default/look-back meaning, so it adds little parameter-level meaning 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?

States a specific verb and resource — fetch a deep snapshot of ONE portfolio — and enumerates exactly what comes back (summary, holdings with weight/sector/return, Bullrun insights). It also names the two siblings it differs from: list_portfolios as the id source and get_portfolio_analytics for risk math, so an agent can route without opening a schema.

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

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

Gives concrete trigger phrasing ("analyze my portfolio", "how am I invested"), an explicit sequencing prerequisite (pass a portfolioId from list_portfolios, call it first if the user hasn't named a portfolio), and an explicit exclusion with the correct alternative for risk/diversification/correlation/factor questions.

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, destructiveHint=false and openWorldHint=false, so the 'Read-only' line is redundant. The one genuinely additive signal is that metrics are derived from already-stored financial statements, though the description says nothing about behavior when statement data is missing or how years of history interact with coverage gaps.

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

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

Front-loads verb and resource, then a dense but purposeful metric list; the trailing 'Read-only.' is redundant with annotations. One long sentence is heavy but no clause is wasted.

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

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

With no output schema, the enumerated metric list effectively stands in for a return-value description, which is the right compensation. What remains uncovered is failure behavior for tickers lacking sufficient statement history, but for a scoped read-only compute tool this is close to 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 100%, so ticker formatting, years bounds, and the WACC/tax-rate fallbacks are already fully documented in the schema. The description reinforces the supplied-WACC dependency ('ROIC-vs-supplied-WACC') but adds no syntax or edge-case meaning beyond it, which is the expected baseline-3 case.

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?

Uses a specific verb ('Compute') plus a named resource ('annual quality, moat, earnings-quality, and capital-allocation metrics') scoped to 'one exact Bullrun ticker', and enumerates the concrete metrics produced. This clearly separates it from siblings like get_stock_metrics (point-in-time ratios) and get_financial_history (raw statements).

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?

Implies the use case ('from existing financial statements' for a single ticker) but never states when to choose this over get_stock_metrics or get_financial_history, nor any prerequisites such as needing statement coverage. Usage is inferable rather than directed.

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, destructiveHint=false and openWorldHint=false, and the description's 'Read-only' merely restates that. The only added behavioral signal is that a single 'exact' ticker scopes the call, with nothing about result shape, periodicity, or how missing breakdown data is handled.

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 what it fetches, followed by the analytical motivation. The trailing 'Read-only.' is a fragment that only duplicates the annotations and is slight 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?

For a simple three-parameter read tool with full schema coverage, the core is covered, but there is no output schema and the description never indicates what a breakdown row contains (values, period, currency, hierarchy). An agent still can't tell what it will get back.

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 clearly documented ticker, dimension enum, and limit. The description echoes the dimension list and the 'one exact ticker' constraint but adds no format or semantics beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (fetch) and resource (revenue breakdown rows) and enumerates the dimensions available, so an agent can tell it apart from a blended-revenue or KPI tool. It does not name a specific sibling, so the differentiation is conceptual rather than explicit.

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

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

'Use this to separate cyclical businesses from recurring segments or inspect geographic exposure instead of relying on blended revenue' gives a clear positive trigger and implicitly steers away from blended-revenue tools. No when-not-to-use or prerequisite conditions are stated.

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

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

Annotations already declare read-only and non-destructive behavior, and the description adds useful context beyond that: band-crossing semantics, output fields like prior/current score and driving input, and the distinction between real movements and coverage-driven changes. The final 'Read-only' is redundant with annotations, but the rest adds substantive behavioral detail.

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

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

The core definition is front-loaded, followed by concrete use cases and a useful scope clarification. It is slightly dense and the final 'Read-only' repeats an annotation, but most sentences earn their 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?

With no output schema, the description does a good job naming the returned fields and explaining the band-change concept. It does not cover pagination or limit behavior, but the core filters and output semantics are sufficiently clear for an agent to call it correctly.

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

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

Schema coverage is 80%, so the baseline is 3. The description reinforces the meaning of the days window and the band-change/stable-basis distinction, but it does not add meaning for the limit parameter and largely relies on the schema for the rest.

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

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

The description states a specific resource and behavior: companies whose Bullrun composite risk score crossed into a different band within the last N days, including prior/current score and the move. It clearly distinguishes this from a general company-risk lookup by emphasizing band changes rather than small score drift.

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 use cases such as 'what got riskier this week' and 'risk deteriorations I should know about,' plus a watchlist workflow that points to get_company_risk afterwards. It also clarifies the key exclusion: band changes, not small score drift.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the trailing 'Read-only.' is redundant. Beyond that, the description adds real behavioral context: prices are in the listing's trading currency while financials are in their own sourceCurrency, and native vs. suffixed tickers only resolve when exactly one listing matches. It stops short of mentioning data freshness/delay or the failure mode when a ticker is ambiguous.

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

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

Front-loaded with the payload definition, then currency semantics, then ticker resolution rules — a sensible information order. The mid-sentence enumeration of a dozen financial line items is dense but each item is genuinely part of the contract, so it earns its space; the redundant 'Read-only.' is the only clear 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?

There is no output schema, so the description must carry the return contract itself, and it does: identity fields, OHLCV, valuation ratios, the full financial statement subset, plus units/currency for each group. Combined with the ticker-resolution guidance, an agent has everything needed to call it and interpret the response.

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 description coverage the baseline is 3, and the description earns an increment by elaborating the resolution semantics around the single ticker parameter — suffix retention for Asian listings (6324.T, 0700.HK) versus bare codes (005930) and the one-listing-match rule. This meaningfully reduces the chance of a malformed ticker even though it partly restates the schema text.

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?

It uses a specific verb ('Fetch a consolidated metrics snapshot') plus a clearly scoped resource (single stock by ticker) and enumerates the exact payload groups: identity, latest OHLCV, valuation, reported financials, description. This is far more specific than a name restatement, though it never explicitly contrasts itself with overlapping siblings such as get_stock_price_history, get_financial_history, or get_valuation_model, so an agent must infer that 'consolidated' means the one-shot bundle.

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?

Strong operational guidance on the input: 'Use the listing ticker returned by search_stocks', concrete US/EU/Asia examples, the exchange-suffix convention, and a fallback ('search by company name or ISIN if unsure'). What it lacks is guidance on when to prefer this snapshot over the sibling history/valuation tools, so the usage half is covered but the alternative-selection half is not.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, but the description adds substantive context they cannot carry: the 2600-row bounded source window, that date filters apply only inside that window and cannot page older, that provider split/dividend adjustment is unknown so returns are not verified total returns, and that missing warm-up stays null with no synthetic sessions or intraday/live quotes. These are exactly the caveats an agent needs to avoid over-claiming results.

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

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

The core capability and its scope lead the description, followed by the routing hint and then the caveats, which is the right order. It is dense but nearly every clause carries information; the only mild bloat is the trailing 'Read-only.' which duplicates readOnlyHint and the compound 'no synthetic sessions, intraday data or live quote claims' phrasing.

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 8-parameter analytical tool with no output schema, the description covers scope, aggregation semantics, indicator warm-up/nulls, data-adjustment uncertainty, and hard window limits. An agent knows what it will get, what it will not get, and where the boundaries are before calling it.

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

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

Schema coverage is 100%, so every parameter including limit, startDate/endDate, interval, indicators, and the period knobs is already documented at the field level; that sets the baseline at 3. The description reinforces the important limit/date interaction ('dates filter that bounded window') and the determinism of indicators, but adds little parameter-level detail the schema does not already supply.

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

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

States a specific verb and resource ('Read bounded stored stock OHLCV history') plus the exact shape of the output (ascending daily/weekly/monthly bars with returns, drawdown, and optional SMA/EMA/RSI/MACD). It explicitly names the sibling it is not ('use get_stock_metrics for a latest company snapshot'), so an agent can route between them without opening either schema.

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

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

Gives a clear use context ('price trends, volatility context and technical analysis') and names one concrete alternative with the condition that selects it (latest snapshot → get_stock_metrics). It stops short of covering adjacent siblings like get_financial_history or get_etf_timeseries, and there is no explicit when-not guidance beyond the snapshot case.

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

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

Annotations already cover read-only/no-destruction, so the bar is lower, and the description still adds real substance: nightly recompute cadence, the sign convention of the gap ('positive = trades below its typical multiple'), the two financial bases with a non-US coverage caveat, and the descriptive-not-advisory framing. It does not say what happens when a ticker has no score or partial fundamentals, which is the main remaining behavioral gap.

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

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

The most decision-relevant facts (what it is, scope, cadence) are front-loaded, followed by model mechanics and then use cases. It is dense and long-ish, but each block earns its place except the gap-formula detail, which is more than an agent needs to select the 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?

No output schema exists, and the description compensates by enumerating the returned quantities (gap, implied model-typical P/E, percentile, rank in universe, 1-year relative return rank) for both valuation and forecast. For a single-parameter read-only tool with full annotation coverage, nothing needed to call or interpret it is missing.

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

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

Schema coverage is 100% and the tickers parameter already carries a detailed description including suffix handling and search_stocks guidance, so the schema does the heavy lifting. The description only echoes the 1-10 cardinality and adds a note that annual financials cover most non-US companies, which marginally informs which listings resolve. 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 states a specific verb and resource: proprietary ML valuation and forecast scores for 1-10 stocks, recomputed nightly, with the exact model (LightGBM P/E or price/sales) and gap formula spelled out. An agent knows precisely what it gets back. It stops short of naming the nearest sibling (screen_valuation_model, which presumably ranks a universe) or distinguishing itself from get_forward_estimates, so it is clear but not sibling-differentiating.

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 in quoted form ('is X cheap or expensive', 'what's X's fair P/E', 'compare valuations of X, Y, Z') plus a negative boundary: 'Descriptive context, not a price target or recommendation.' That is clear context and one exclusion, but no alternative tool is named for the screening/ranking case or for forward-estimate needs.

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

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

Goes well beyond the readOnly/non-destructive annotations by disclosing the OAuth requirement and read:portfolios scope, that only the authenticated user's own data is returned, and the privacyMode default ('full' returns absolute $ vs 'weights_only' strips cash/value/cost basis). These are material behavioral facts an agent cannot infer from structured fields.

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

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

Front-loaded with the 'Use when...' trigger and concrete user phrasings, then routing, then auth/privacy caveats. Each sentence serves a purpose, though the long list of example utterances and the return-field enumeration make it denser than strictly necessary.

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

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

With no output schema, the description compensates by enumerating the returned fields and noting position counts and computed summaries. Combined with the routing guidance, auth requirements, and default privacy behavior, an agent has everything needed to invoke it correctly and interpret the result.

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

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

Schema coverage is already 100% for the single privacyMode parameter, but the description adds practical meaning: that the default is 'full' and what 'weights_only' actually hides versus preserves. It does not add example values or caveats beyond that, so it is a modest improvement over the schema rather than a full substitute.

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

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

States a specific verb ('Lists') and resource ('signed-in Bullrun user's virtual portfolios') and enumerates the computed fields returned (value, day change, cost basis, return, position counts). It is clearly distinguished from siblings like get_portfolio_context and get_portfolio_analytics by positioning itself as the entry point that yields a portfolioId for those 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?

Explicitly names the triggering situations with concrete example utterances ('my portfolios', 'how are my investments doing'), and gives a routing rule: use this first when no specific portfolio is named, then pass the resulting portfolioId to the context/analytics tools. Alternatives and the condition selecting them are both stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds meaningful context beyond those annotations: OAuth scope requirement read:shortlist, the returned content (tickers with dated stored prices), and behavioral boundaries. It does not discuss empty-state behavior or ordering, keeping it shy of a 5.

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

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

Three sentences, all front-loaded and purposeful: purpose/return content, auth and usage trigger, then exclusions. Nothing is wasted or buried.

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

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

No parameters and no output schema, so the description carries the return-value burden and does so by naming tickers and dated stored prices. Combined with the auth requirement and usage trigger, an agent has enough to invoke the tool correctly.

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

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

The tool has zero parameters, so the baseline is 4. There are no parameter semantics to explain, and the description correctly focuses on purpose, auth, and return content instead.

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

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

States a specific verb and resource: reading the signed-in user's saved Research Shortlist of stock/ETF tickers with dated stored prices. It also distinguishes the tool from save_research_shortlist and screening tools by clarifying that it does not evaluate a screen, schedule monitoring, or send notifications.

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

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

Gives a clear trigger: 'Use after the user asks for their saved research queue,' and useful exclusions around screening, monitoring, and notifications. It stops short of explicitly naming save_research_shortlist as the write counterpart, so it is strong but not fully complete.

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

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

Beyond the annotations (idempotent, non-destructive, closed-world write), it discloses the required OAuth scope write:shortlist and what to do on a missing scope, that existing entries are retained, and that each ticker is saved independently with partial failures reported so only failed tickers are retried. These are non-obvious traits an agent could not infer from the schema. It stops short of describing the response payload shape, which matters since there is no output schema.

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

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

Five short sentences, front-loaded with purpose and scope, followed by prerequisites, idempotency, failure semantics and exclusions. Every sentence contributes a distinct, actionable fact with no filler.

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

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

For a single-parameter write tool with no output schema, the description still covers auth requirements, idempotency, merge-vs-replace behavior, partial-failure reporting and retry strategy. Nothing an agent needs to invoke it correctly, or to interpret a mixed success result, is missing.

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

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

Schema coverage is 100% and already enforces minItems 1, maxItems 20, the ticker pattern and an example, so the description's '1-20 exact ... tickers' largely restates it. It does add the constraint that tickers must be exact Bullrun stock or ETF listings resolved via search_stocks/search_etfs, which is semantic guidance the pattern alone cannot convey.

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

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

States a specific verb (add), resource (Research Shortlist), and precise scope: 1-20 exact listing tickers for the signed-in user. It also explicitly contrasts itself with adjacent capabilities (portfolio creation, monitoring, notifications), so it is separable from siblings like create_portfolio_draft or list_research_shortlist.

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

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

Gives the triggering condition ('when the user asks to save them'), a prerequisite step ('Resolve ambiguous names with search_stocks/search_etfs first'), and explicit exclusions ('Does not create a portfolio, schedule monitoring or send notifications'). An agent knows both when to call it and which siblings to route to instead.

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

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

Annotations already establish that the tool is read-only, non-destructive, and closed-world. The description adds valuable behavioral context beyond annotations: the screen is expensive, request limits depend on connection/plan, one precise screen should be built to conserve allowance, and the result reports evaluatedCount and matchCount. It does not detail output shape, but an output schema exists, so this is a minor gap.

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

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

The description is front-loaded with the key differentiator and use case, then adds cost guidance and unit semantics. It is appropriately long for a 24-parameter screening tool, though the long attribute list and final "Read-only" repetition slightly reduce concision.

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, 24 parameters, 100% schema description coverage, annotations, and an output schema, the description provides the crucial context: full-universe scope, alternative tool distinction, cost implications, and unit conventions. Nothing essential for correct invocation is missing from the description.

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 the 24 parameters thoroughly, making 3 the appropriate baseline. The description adds some useful global semantics, especially that percentages are percentage points and that holdingSearch matches funds by constituent holdings, but it does not meaningfully expand on parameter behavior 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 description gives a specific verb and resource: screen the whole ETF universe by numeric rules and fund attributes. It lists the exact metric groups and attribute dimensions, and explicitly distinguishes this tool from search_etfs by full-universe evaluation versus bounded candidate scanning. An agent can identify the tool and its scope without opening the schema.

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

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

It explicitly says to prefer this over search_etfs for "cheapest / largest / best performing / most liquid" questions and explains why: search_etfs only filters a bounded scan while this evaluates the full universe. It also notes that holdingSearch is a constituent look-through and that building one precise screen conserves allowance. This gives clear when-to-use and alternative selection 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 destructiveHint=false, and the description stays consistent while adding real substance: per-row return fields (ticker, score, band and its meaning, direction, move, driving input), plus universe-level band distribution and band-change counts at the last recompute. The clarification that it ranks readings rather than flagging companies to avoid is behavioral context found nowhere in the structured fields.

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

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

Two dense sentences that front-load the ranking scope, followed by returns, use cases, sibling routing and a caveat — well ordered with no filler. Slight deduction for restating 'Read-only', which the annotations already establish, and for the very long mechanism parenthetical.

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 nine optional parameters and no output schema, the description compensates by enumerating the returned row fields and the aggregate payload. Filter dimensions, mechanism semantics, the includeSlices behavior and the drill-down path are all covered, so an agent could call this correctly without further inference.

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 78%, so the schema carries most parameter documentation. The description still adds useful framing — the six dial names grouped as filterable 'dial coverage', the band/sector/country filter set, and a concrete demonstration of includeSlices ('how risky is tech vs utilities') — though it does not explain limit/offset or sortBy beyond what the schema already states.

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

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

States a specific verb (rank), a specific resource (Bullrun's ~9,000-company scored universe) and the ranking basis (composite risk or one of six mechanism dials). It distinguishes itself from get_company_risk by explicitly routing row-level drill-down there, so an agent can separate it from siblings like get_risk_movers and screen_stocks.

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

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

Gives four concrete query shapes ('which large caps have stretched leverage', 'most concentrated supply chains in semiconductors', 'calmest German industrials', 'how risky is tech vs utilities' with includeSlices) and names the alternative tool for follow-up. It also adds a negative guideline — 'A ranking of readings, not of companies to avoid' — which prevents misuse of the output.

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

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

Goes beyond the readOnlyHint annotation by disclosing that action=run consumes a metered screening budget, that list_presets performs no backend request, and that presets are mechanical starting points rather than recommendations or famous-investor strategies. Return shape is not described, but the operationally important traits are covered.

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, front-loaded with the action and resource, then the mode split, then cost, then scope of custom screens. Dense but every sentence carries usable information; the long compound sentence about custom-screen features is the only mild readability cost.

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 17-param tool with no output schema, the description covers the crucial preset-vs-custom dichotomy, the metering budget and the preset lookback constraints. It does not describe what a run returns (matching tickers plus metric values, sorting behavior), which would help given no output schema exists.

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 all 17 parameters are already documented in detail; baseline is 3. The description adds a high-level summary (sector/industry/country, listing controls, lookback, AND/OR groups, money units) that mirrors the schema but introduces no new syntax or constraints.

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

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

States a specific verb and resource ('Screen the global Bullrun stock universe') and names the mechanism (app rule engine with custom fundamental rules or named presets). This clearly separates it from siblings like search_stocks (lookup), screen_etfs and screen_valuation_model (different universes).

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 distinguishes action=list_presets (discloses thresholds, no backend request) from action=run (executes, uses metered budget) and tells the agent custom screens vs presets. It lacks a direct 'use search_stocks instead if you want a single company' routing, but the internal mode selection is unambiguous.

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

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

Annotations cover read-only/destructive/open-world, but the description adds real context: the universe cutoff, what each row returns (valuation gap, model-typical vs current P/E, percentile, rank, data quality), and an explicit caveat that the gap is descriptive context rather than a return prediction. That interpretation constraint materially changes how an agent presents results.

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

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

Front-loaded with the verb and universe, and every sentence carries new information (row contents, caveat, follow-ups). It is a dense paragraph that could be segmented for scanability, but there is no filler.

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

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

With no output schema, the description compensates by naming the returned fields and the universe scope, and it closes the loop with follow-up tools so the agent knows this is a starting point. Nothing needed to invoke correctly is missing.

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

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

Schema coverage is 86%, so the schema already documents end, model, sector, country, coverage and exchange in detail. The description restates the model families and filter dimensions in prose but adds little syntax or semantics beyond the enum descriptions, so baseline 3 applies.

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

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

States a specific verb (Rank) and resource (the whole scored stock universe, market cap >= $100M) plus the exact ranking basis (Bullrun ML valuation gap or forecast signal). This is unmistakably distinguishable from generic siblings like screen_stocks or get_valuation_model.

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

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

Gives concrete example queries ('cheapest stocks vs fundamentals in Europe', 'best forecast scores in Japan') and prescribes follow-up tools (get_stock_metrics, get_company_risk, get_quality_moat_metrics). It never states when to prefer screen_stocks or get_valuation_model instead, so no 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?

Annotations already declare readOnlyHint/destructiveHint, but the description adds genuinely non-obvious behavior: minAum and minYieldTtmPct are only applied to a bounded profile-enriched candidate scan, and results are not exhaustive when candidateCapReached is true. That is a real correctness caveat an agent cannot infer from the schema alone.

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, front-loaded with what it does, then alternative routing, then the exhaustiveness caveat, then sibling pointers. No filler; the trailing 'Read-only' is mildly redundant with annotations but negligible.

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 optional-filter tool with an output schema, the description supplies the routing and the one behavioral trap (bounded candidate scan). Minor gap: three parameters (includeInactive, includeSecondary, sortDirection) are undocumented in both schema and description, so an agent must guess their effect.

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 83%, so the baseline is 3; the description goes beyond by clarifying the scope of minAum/minYieldTtmPct (bounded candidate scan, not the whole universe) and by framing search as the free-text entry point vs. exact-match facet filters. It does not clarify includeInactive, includeSecondary or sortDirection, which lack schema descriptions.

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

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

States a specific verb and resource (look up ETFs) plus the lookup keys (name, ticker, ISIN) and the filter families available, so an agent immediately knows this is a known-item lookup with faceted filtering, distinct from the screening and per-fund siblings.

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

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

Explicitly says 'Best for finding a known fund', names screen_etfs as the alternative for ranking questions with quoted example queries ('cheapest', 'largest'), and routes single-listing, ISIN-resolution and constituents use cases to get_etf_snapshot, get_etf_fund and get_etf_holdings respectively. When-to-use, when-not-to-use and alternatives are all present.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint=false, destructiveHint=false), yet the description adds real behavioral substance: ambiguity handling ('never picks a listing when alternatives remain', 'Returns explicit ambiguous candidates') and venue reconciliation of Yahoo suffixes with share-class dots preserved. These are non-obvious resolution behaviors an agent must anticipate when interpreting results.

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

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

Front-loaded with the core resolve-then-research framing, and each sentence carries distinct information about resolution semantics or scope limits. The trailing 'Read-only.' duplicates the readOnlyHint annotation and is the one line that doesn't earn 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?

With eight parameters, no output schema, and a resolution-oriented purpose, the description supplies what the schema cannot: the ambiguity contract, the no-enrichment boundary, venue-suffix handling, and result shape ('explicit ambiguous candidates'). An agent can call this correctly and interpret its output without further information.

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

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

Schema description coverage is 100%, so every parameter including country, currency, exchange, quoteType, includeInactive and includeSecondary is already documented, and the description's filter list ('exchange/MIC, country, currency and instrument-type') merely restates it. The one genuine addition beyond the schema is that native share-class ticker dots are preserved. Baseline 3 is appropriate.

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

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

States a precise verb and resource ('Resolve a company name, native ticker, ISIN or exchange-qualified symbol to Bullrun listings') and explicitly positions itself as a pre-step before 'exact-ticker research tools'. This clearly separates it from screen_stocks (screening) and search_etfs (fund lookup), which an agent can distinguish without opening any schema.

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

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

Gives an explicit sequencing rule ('before calling exact-ticker research tools') and a scope exclusion ('No enrichment or market-data refresh'). It also notes that quoteType ETF/ALL 'does not make stock-only research tools valid for funds', steering fund lookups elsewhere. It stops short of naming search_etfs as the direct alternative, so the routing is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the trailing 'Read-only' adds nothing. However the description does disclose real behavioral content beyond annotations: the exclusions list and the fact that the output reports direct charges plus ending-value drag, telling an agent this is a deterministic no-side-effect what-if model.

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

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

Front-loaded with the core action, and the exclusion sentence earns its place by preventing misuse of the results. The standalone 'Read-only.' fragment is pure duplication of the readOnlyHint annotation and is the one wasted element.

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