Bullrun

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

Discloses that it generates a reviewable paper-portfolio draft, requires OAuth with write:drafts scope and a Bullrun Pro account, is draft-only (never changes live positions), and explains the post-draft workflow (appears in 'Pending AI drafts'). This goes well beyond the minimal annotations provided.

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 comprehensive and well-structured, starting with the primary use case, followed by behavioral details, prerequisites, and contrast with sibling. While it is verbose, every sentence serves a purpose, making it efficient for an agent 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?

Despite lacking an output schema, the description fully explains the output (a reviewable portfolio draft) and covers all necessary behavioral aspects, prerequisites, and workflow. No gaps remain for an agent to misuse 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?

With 100% schema description coverage, the baseline is 3. The description adds value by explaining optional behavior of the 'prompt' parameter (server may collect brief directly) and the default for 'instrumentUniverse'. The added context enhances understanding beyond the 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?

The description clearly states the tool creates a brand-new portfolio draft, using verbs like 'BUILD' and 'PROPOSE'. It distinguishes from the sibling tool 'create_position_draft' which handles additions to existing portfolios.

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 tells when to use ('when the user wants you to BUILD or PROPOSE a brand-new portfolio') and when not to use (for additions to existing portfolios, use 'create_position_draft'). Also provides guidance on handling vague briefs with multiple-choice 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 only indicate non-read-only and non-destructive, but description adds critical behavioral traits: the draft is saved for user review, never changes live positions, tickers are used verbatim, unresolved tickers are skipped, and OAuth scope requirements are mentioned. This far exceeds the annotation 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?

The description is somewhat long but well-organized: it leads with the primary use case, explains behavior, differentiates from sibling, mentions scope and limitations, and ends with alternative. Every sentence adds value, though minor redundancy (e.g., 'never re-selects tickers' repeated) prevents a 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?

Given the tool has 4 parameters (1 required) and no output schema, the description is remarkably complete. It covers the draft-only nature, ticker validity constraints, error behavior (unresolved skipped), warning against using both weight and amount, and clarifies that no live positions are affected. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description mostly paraphrases schema details (e.g., name default, weight as percent, cashPct override) without adding significant new semantics. Some reinforcement of verbatim usage is present but not enough to raise the score.

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

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

The description clearly states the tool saves a portfolio draft from user-decided holdings, using specific verbs like 'persists' and 'save as-is'. It explicitly distinguishes from sibling create_portfolio_draft by noting this tool does NOT use the LLM and NEVER re-selects tickers, making its purpose unmistakable.

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

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

Provides explicit guidance on when to use ('when you have ALREADY decided the exact holdings') and when not to ('for vague briefs, use create_portfolio_draft instead'). Also mentions prerequisites (tickers must exist in Bullrun's universe) and suggests alternative tools to confirm tickers (query_etfs, screen_stocks, get_stock_metrics).

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?

Disclosures beyond annotations: requires OAuth write:drafts scope and Bullrun Pro account; states drafts are saved to account and appear in Pending AI drafts for review; confirms it never changes live holdings. No contradiction with annotations.

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

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

Description is verbose but well-structured, starting with usage triggers, then functionality, requirements, alternatives, and parameter guidance. Every sentence is informative, though slightly longer than ideal.

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

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

Covers purpose, usage context, prerequisites, what it does/doesn't do, alternatives, and parameter guidance. Missing explicit mention of return value (e.g., draft ID), but acceptable given tool's action-oriented nature.

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 description adds value: portfolioId suggests using list_portfolios first; maxPositions explains default and single-use; instrumentUniverse describes enum options. Also includes guidance on parameter selection.

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

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

Description clearly states the tool generates reviewable suggested additions for an existing portfolio, using specific verbs like 'BUY' or 'ADD'. It distinguishes from siblings by referencing create_portfolio_draft (for new portfolios) and get_portfolio_analytics (for testing specific tickers).

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

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

Explicitly states when to use (user asks what to buy/add to existing portfolio) and when not (no live holdings changes). Provides alternative tools for different scenarios and advises to confirm portfolio and number of ideas if unclear.

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

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

Annotations provide readOnlyHint=true, and description adds extensive behavioral details: authentication, identity, OAuth scopes, portfolio usage limits, per-tool entitlement map (e.g., which tools are free vs Pro-only). No contradiction with annotations.

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

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

Description is fairly detailed but front-loaded with purpose. Every sentence adds value, though could be slightly more concise by combining some statements. Still well-structured.

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

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

Given zero parameters and no output schema, the description fully covers what the tool returns (authentication status, identity, scopes, portfolio usage, per-tool entitlements). No gaps remain for the agent to understand behavior.

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

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

Input schema has zero parameters. Baseline is 4 per rule. Description does not need to add parameter info and appropriately states no parameters are required.

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 specific verbs 'Discover what the connected Bullrun account can do' and clearly identifies the resource (Bullrun account). It distinguishes this discovery tool from sibling action tools by stating it is called before attempting actions.

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

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

Explicitly states when to call: 'first when a draft/write tool might be gated, or to confirm which account a request will act on.' Provides context about what it reports and implies not needed for already-known read-only tasks.

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 aligns with the readOnlyHint annotation by stating 'Read-only.' It adds behavioral context about returning 'speaker-tagged transcript chunks' with configurable chunk size and count, though does not detail pagination or ordering. This adds value beyond the annotation.

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

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

The description consists of two concise sentences with no fluff. The first sentence clearly states the action and parameters, and the second adds usage guidance, making every sentence 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?

Given the tool has no output schema, the description provides a high-level understanding of the return type ('speaker-tagged transcript chunks') and mentions maxCharsPerChunk, which aids in expectation setting. However, it lacks details on the exact structure of each chunk, which is a minor gap. Still, overall informative enough.

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?

All 6 parameters have descriptions in the input schema, achieving 100% coverage. The description reinforces the filtering options but does not add significant new meaning beyond the schema, so a 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 clearly states the tool fetches speaker-tagged earnings call transcript chunks for a specific ticker, with optional fiscal period and search text filters. It distinguishes itself from sibling tools focusing on financial statements by highlighting qualitative judgment and management guidance language.

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

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

The description explicitly says to use this tool for management guidance language, analyst Q&A, and qualitative judgment not visible in financial statements. While it doesn't list alternatives or when not to use, the context implies it is for non-numeric insights, differentiating from financial history or forward estimates.

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, which aligns with description. Description adds value by detailing return groups (income statement, balance sheet, cash flow, etc.) and growth checks, going beyond annotations.

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

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

Two sentences, front-loaded with action and scope, no redundant words. Every sentence earns its place.

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

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

No output schema, so description must explain output. It lists return groups and mentions growth checks. Provides sufficient context for an agent to understand what the tool delivers.

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 descriptions cover 100% of parameters. Description reinforces parameter meaning and adds context about 'annual growth/CAGR consistency checks' not in schema, providing extra semantic value.

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

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

Description clearly states the verb ('Fetch'), resource ('historical financial statements'), and scope ('1-15 years for one exact Bullrun ticker'). Distinct from siblings like get_forward_estimates or get_quality_moat_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?

Explicitly states when to use: 'when evaluating multi-year revenue/net-income growth, margin trajectories, etc.' Does not list when not to use, but context is clear given sibling tools.

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

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

Annotations already declare readOnlyHint=true, and the description confirms 'Read-only.' It adds value by disclosing that the tool derives simple forward P/E and PEG-style context from the latest close. However, it does not mention rate limits, authentication needs, or data freshness beyond what annotations imply.

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 the core action. The first sentence covers the primary purpose and specificity; the second adds derivation context. No redundant or extraneous words.

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

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

Given no output schema, the description adequately explains return data (estimates, guidance, revisions, derived valuations) and constraints (exact ticker, read-only). It covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for the overall data (estimates, guidance, etc.) but does not elaborate on individual parameters beyond what the schema already provides (e.g., limit max, periodType enum). It meets the baseline without significant enhancement.

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

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

The description clearly states it fetches forward consensus estimates (revenue/EPS/EBITDA), management guidance ranges, and estimate-revision percentages for a Bullrun ticker. It also mentions deriving P/E and PEG context. This specific verb-resource combination distinguishes it from sibling tools like get_financial_history or get_quality_moat_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?

The description implies read-only usage and requires an exact ticker, but does not explicitly state when to use this tool over alternatives (e.g., get_stock_metrics for trailing data). No 'when-not' or alternative tool names are provided, leaving the agent to infer context.

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

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

Annotations declare readOnlyHint=true, and the description repeats 'Read-only', adding no further behavioral traits. No mention of rate limits, data freshness, or any side effects. The description adds minimal value beyond the annotation.

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

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

Two sentences: the first conveys the core purpose and examples, the second clarifies read-only nature. No filler words, front-loaded with key information.

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

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

Given no output schema, the description does not explain return values. However, the tool name and examples imply the result format. All 4 parameters are documented in the schema. It is adequate for a straightforward fetch tool, but lacks details on pagination or response structure.

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

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

Schema coverage is 100%, so baseline is 3. The description lists example metrics like ARR, NRR, etc., but does not add semantic details beyond the schema (e.g., format requirements for metricKey or ticker). It provides context but not substantial added meaning.

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

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

The description clearly states the verb 'fetch' and specifies the resource: 'period-specific operating KPIs and unit-economics metrics for one exact Bullrun ticker'. It lists example metrics (ARR, NRR, etc.) and distinguishes itself from sibling tools like get_financial_history or get_forward_estimates by focusing on operational KPIs.

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

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

The description indicates it is for a single Bullrun ticker and is read-only, providing clear context. However, it does not explicitly state when to use this tool versus alternatives like get_quality_moat_metrics or get_revenue_breakdown, nor does it exclude certain scenarios.

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

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

Beyond the readOnlyHint annotation, the description discloses that risk math drops unpriced/unmatched holdings with renormalization, that the response leads with a coverage banner showing excluded holdings, and explains privacyMode effects. No contradiction with annotations.

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

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

The description is well-structured, front-loaded with usage context and examples, followed by technical details, caveats, and alternative tools. Every sentence adds value, no fluff.

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

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

Given the tool's complexity and no output schema, the description covers return types (matrices, exposures, scenario tests, candidate analysis), behavior (data dropping, coverage banner), auth requirements, and privacy modes. It is fully complete for agent understanding.

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?

All 5 parameters have schema descriptions (100% coverage). The description adds extra meaning: explains candidateTicker as Bullrun ticker with examples, clarifies candidateWeightPct default, and describes privacyMode options in more detail.

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

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

The description clearly states the tool fetches portfolio-level relationship analytics including correlation, covariance, risk contributions, exposures, factor scores, scenario tests, and candidate fit analysis. It provides specific verb and resource, and distinguishes from sibling tool get_portfolio_context.

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 'Use when the user asks about THEIR portfolio's risk, diversification, or concentration, or whether to add a stock' with example queries. It guides to pass portfolioId from list_portfolios and when to set candidateTicker. It also points to get_portfolio_context for plain holdings snapshot.

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

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

Annotations declare readOnlyHint=true, and description confirms 'Read-only'. Additionally, description discloses OAuth requirement, data ownership (caller's own data), and critical behavioral details about coverage limitations—that unmatched holdings have no weight/sector/insight—and warns not to present matched-only figures as whole. This goes well beyond annotations.

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

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

Description is fairly long but well-structured and front-loaded with usage condition. Every sentence adds value (usage, return content, prerequisite, coverage warning, alternative, auth, privacyMode). Could be slightly trimmed but it's efficient and clear.

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

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

Despite no output schema, description comprehensively explains return values: summary, holdings with details, insights, coverage banner, and privacyMode behavior. Agent has enough info to interpret response correctly. High complexity is fully addressed.

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% with descriptions for all 3 parameters. The description adds minor context like calling list_portfolios first for portfolioId and default days, but these are already in schema. Little new semantic value beyond what schema provides, so baseline 3.

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

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

Description clearly states the tool is for reviewing/analyzing a user's portfolio, listing specific verb phrases like 'look at, review, analyze' and resource 'portfolio/holdings/positions'. It distinguishes from sibling tool get_portfolio_analytics by specifying when to use that alternative for risk/diversification analysis.

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

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

Explicitly states when to use: when user asks to review portfolio/holdings. Provides clear alternative: for risk/diversification use get_portfolio_analytics. Gives prerequisite: call list_portfolios first if portfolio not named. This fully guides agent on context.

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

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

The description repeats the 'Read-only' annotation but adds no further behavioral context beyond listing the computed metrics. Since the annotation already provides readOnlyHint: true, the description adds moderate value by detailing the metrics but lacks info on side effects, auth needs, or rate 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 consists of two sentences that efficiently convey the tool's purpose, inputs, and outputs. No extraneous information is present, and the key details are front-loaded.

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

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

The tool has no output schema, so the description should guide on return structure. While it lists the computed metrics, it does not describe the output format (e.g., a table, JSON object, or time series). Given the tool's complexity, this is a moderate 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?

With 100% schema coverage, the baseline is 3. The description adds minimal extra meaning beyond the schema; it reiterates the 'exact Bullrun ticker' constraint already present in the ticker parameter description but does not elaborate on years, estimatedWaccPct, or taxRateFallbackPct.

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 the verb 'Compute' and specifies the resource 'annual quality, moat, earnings-quality, and capital-allocation metrics for one exact Bullrun ticker'. It lists specific metrics (ROIC, ROE/ROA, etc.), clearly distinguishing it from sibling tools like get_stock_metrics or get_financial_history.

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

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

The description states the tool is for 'one exact Bullrun ticker' and uses 'existing financial statements'. It provides guidance on the ticker format ('exact Bullrun ticker') and declares the tool 'Read-only'. However, it does not explicitly mention when to use this tool versus alternatives or when not to use it.

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. The description states 'Read-only' and adds context about the data's purpose (separate business segments), but does not disclose additional behavioral traits beyond the annotation.

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

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

Two sentences, front-loaded with action and resource, no unnecessary words.

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

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

Given full schema coverage, readOnly annotation, and no output schema, the description covers the tool's purpose, usage, and read-only nature. Could mention return format or pagination details, but the limit parameter addresses this.

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

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

Schema description coverage is 100%, so the description adds minimal new meaning. It reinforces the ticker requirement and lists dimensions, but the schema already documents all parameters with descriptions and enums.

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

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

The description clearly states the verb 'Fetch' and the resource 'revenue breakdown rows', specifies the dimensions (segment, geography, product, customer, other), and distinguishes from siblings by emphasizing use for inspecting breakdowns over blended revenue.

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 concrete use cases (separating cyclical vs recurring, inspecting geography) and requires an exact Bullrun ticker. Lacks explicit when-not-to-use or alternative tools, but context from sibling list and description is sufficient.

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

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

Annotations already declare readOnlyHint=true; description reinforces read-only nature and adds behavioral details: how to handle ticker errors, the exact ticker format expected, and the scope of data returned. No contradictions.

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

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

Description is concise (4-5 sentences, ~150 words) and well-structured: main purpose first, then data groups, then ticker warnings, then fallback. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description comprehensively lists all return data groups (identity, price, valuation, financials, description) and addresses error handling (use screen_stocks). Fully covers tool behavior for an agent.

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

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

Schema coverage is 100% for the single 'ticker' parameter, but the description adds substantial meaning: explains ticker format in detail with examples (e.g., AAPL, BMW, not BMW.DE) and describes the entire return structure, going beyond what the JSON 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 clearly states the tool fetches a consolidated metrics snapshot for a single stock by ticker, listing all data groups (identity, price, valuation, financials, description). It distinguishes itself from sibling 'screen_stocks' by implying this is for a single known ticker.

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

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

Explicitly states when to use (single stock snapshot) and when not (if ticker returns no data, use screen_stocks). Provides detailed ticker format guidance (native local symbol, no Yahoo suffixes) with examples.

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?

Discloses read-only nature (matches annotation), OAuth requirement with read:portfolios scope, returns only user's own data, and explains privacyMode parameter behavior. No contradictions with annotations.

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

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

Three sentences, front-loaded with usage cues, no fluff. Each sentence adds essential 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?

Complete for a simple list tool with one optional parameter and no output schema. Covers purpose, usage, constraints, authentication, and relationship to sibling tools.

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

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

Schema coverage is 100% for the single parameter, but description adds practical context: default is 'full' (absolute $), 'weights_only' hides cash/value/cost-basis. Adds value beyond schema.

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

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

Clearly states it lists the signed-in user's virtual portfolios with summaries, and explicitly distinguishes from siblings like get_portfolio_context (which requires a specific portfolioId). The verb 'list' and resource 'portfolios' are specific.

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

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

Explicitly states when to use: when user refers to 'their portfolios' or holdings without naming a specific portfolio. Also provides guidance to then pass a portfolioId to get_portfolio_context or get_portfolio_analytics, and notes alternatives.

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

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

The description confirms read-only behavior (consistent with annotation) and details the returned data for exact tickers. Beyond annotations, it adds clarity on what the tool produces, but does not disclose potential rate limits or data freshness.

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 long, front-loaded with the primary search capability, and contains no extraneous information. Every phrase adds value.

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

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

Given the complexity (13 optional parameters, no output schema), the description covers core functionality well. It lacks details on default behavior when no input is provided, but the schema provides defaults. Slightly incomplete for a comprehensive 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?

All 13 parameters are fully described in the input schema (100% coverage). The description reiterates some filter purposes but adds no new semantic meaning 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 tool's purpose: search the ETF universe by multiple criteria, and for exact tickers return profile, prices, and holdings. It distinguishes from sibling tools that handle other security types or analyses.

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

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

The description explains when to use the tool (for ETF searching and detailed retrieval) and specifies that for exact tickers it returns additional data. However, it does not explicitly state when not to use it or mention alternatives among siblings.

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

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

Annotations declare readOnlyHint=true, and the description ends with 'Read-only,' which is consistent and adds minimal extra context. The description also states it 'Returns a compact table of matching stocks,' but does not disclose authorization needs, rate limits, or any behavioral quirks beyond what annotations provide. With readOnlyHint already present, the description adds limited value, scoring 3.

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 a single long sentence followed by a short sentence. While it covers all key aspects, it could be more structured (e.g., bullet points for filter categories) and more concise by avoiding the laundry list of parameters. Every sentence is relevant, but the run-on format reduces readability. Adequate but not exemplary.

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 15 parameters, no output schema, and no nested objects, the description covers the purpose, filtering capabilities, and return type ('compact table of matching stocks'). It does not detail the output fields or pagination, but for a read-only screening tool, this level of completeness is sufficient. The description is mostly complete without being exhaustive.

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

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

Schema description coverage is 100%, meaning the input schema already thoroughly documents all 15 parameters. The description lists several filter categories (sector, industry, country, etc.) but does not add new meaning or clarification beyond the schema. For example, it mentions 'AND/OR rule groups' and 'comparison operators,' which are already detailed in the schema. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states the tool screens the global Bullrun stock universe using the same rule engine as the app screener, and lists specific filter criteria (sector, industry, country, etc.). It ends with 'Returns a compact table of matching stocks,' which defines the verb (screen) and resource (stock universe). It also distinguishes from sibling tools like get_stock_metrics or get_financial_history by focusing on rule-based screening.

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

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

The description implies usage for screening stocks with a powerful rule engine, but does not explicitly state when to use this tool versus alternatives (e.g., get_stock_metrics for individual stock data). There is no guidance on when not to use it or prerequisites. It mentions 'same rule engine as the app screener' but lacks direct exclusions or context.

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