FinBridge

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

The annotations already indicate this is not read-only and not idempotent. The description adds the crucial behavioral detail that the operation can remove an existing watchlist entry, not just add one. This is meaningful context beyond the structured annotations and helps the agent predict side effects.

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 entire description is one efficient sentence that states the action and the toggle behavior without fluff. Every part earns its place, and the key behavior is front-loaded.

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

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

For a single-parameter tool with an output schema and annotations already present, the description covers everything needed to invoke it correctly: what it does, the toggle side effect, and the only input. There are no significant missing details.

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

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

Schema description coverage is 100%: the schema already specifies that 'symbol' is a stock code, ticker, or company name. The description adds no additional parameter-level meaning beyond that, so the baseline score 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 ('Add') and resource ('company to the user's watchlist'), and immediately clarifies the toggle behavior: it removes the company if it is already present. This makes the tool's function unambiguous and distinct from the sibling tools, none of which target watchlist toggling.

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 makes the usage context clear: use this tool to add a company to the watchlist, and the same call will remove it if already present. It does not explicitly list alternatives or when-not-to-use conditions, but no sibling tool offers this watchlist-toggle capability, so the guidance is sufficient.

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

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

Annotations already mark it readOnlyHint=true, and the description adds substantial behavioral context: returns are gross, delisted names are included, dividends are excluded, fundamental factors carry a restatement look-ahead, and certain markets/refusals produce explicit errors. It also explains the distinction between IC IR and t-statistic, all beyond what annotations or schema provide.

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

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

The description is long, but the length is earned by the tool's complexity: 10 parameters, a large factor taxonomy, market restrictions, and subtle output semantics. It is front-loaded with the core purpose, then organized into clear sections for args, returns, examples, usage boundaries, and caveats. Every section adds decision-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?

The description covers parameter ranges, factor availability by market, data history limitations, error behavior, output interpretation, and look-ahead concerns. Even though an output schema exists, the description adds necessary interpretive context such as coverage_pct, net_avg, and the meaning of report_age_days. An agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, but the description goes far beyond the schema by explaining the meaning of each factor, market-specific constraints, why rebalance=hold gives non-overlapping observations, the role of coverage_pct, and what slippage_bps affects. It also provides worked examples that map parameter combinations to research questions.

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: 'Measure whether a ranking signal actually separates future returns, point-in-time, on KR/US/TW daily bars from the local finbridge.db.' It also positions the tool relative to its siblings by saying this question comes 'BEFORE a screener', which distinguishes it from screen_canslim, screen_minervini, and similar tools.

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

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

The description gives explicit 'Use when' and 'Don't use for' sections, naming alternatives such as screeners, backtest_portfolio, and any factor requiring market capitalisation. This gives an agent clear routing criteria rather than leaving the decision 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?

The text is rich in caveats (ETF price-return only, not split-adjusted, US history clipping, cost deductions). However, the label parameter description states the run is saved and can be found with get_backtest_runs, while annotations declare readOnlyHint=true; this persistent side effect directly contradicts the read-only annotation, so per rubric this dimension scores 1 despite the other disclosures.

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

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

Well-structured with front-loaded purpose, Args, Returns, Examples, Use/Don't-use, Errors, and Notes, and the example is useful. It is long and repeats the ETF price-return/split-adjustment and total-return caveats in both the opening warning and Notes, so it loses one point for conciseness.

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 11-parameter tool with an output schema, the definition covers input semantics, return shape, examples, error behavior, and data caveats. An agent has enough context to invoke it correctly and to interpret results, and the output schema covers return details.

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

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

Schema coverage is 100%, but the description goes well beyond it: symbol resolution rules, weight normalization, start-date clipping to asset inception, rebalance timing, daily currency conversion via USDKRW/FRED DEXKOUS, initial-value default, and gross-vs-net cost behavior. This materially helps an agent construct correct arguments.

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

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

Opening sentence states a specific verb, resource, and scope: 'Backtest a fixed-weight KR or US portfolio on daily data from the local finbridge.db.' The 'Don't use for' section explicitly separates it from get_stock_prices, screeners, and strategy-backtest tools, so an agent can distinguish it from 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?

'Use when' gives concrete scenarios (what-if since YYYY, comparing allocations, drawdown/volatility analysis). 'Don't use for' names sibling alternatives and the not-yet-available strategy-backtest class, leaving no ambiguity about when to call this 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 declare readOnlyHint and openWorldHint, so the safety profile is already established. The description adds substantial behavioral context: KRW conversion via FRED DEXKOUS, supported quote handling, premium formula, return structure, geo-blocking caveat, and error behavior for unknown symbols and missing FRED keys.

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 organized into clear sections — summary, Args, Returns, Examples, Errors — and every sentence earns its place. The core use case is front-loaded, and the examples and error notes are compact and directly actionable.

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

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

The tool is complex with 5 optional parameters, output schema, and notable caveats, and the description covers all of it: parameter defaults, supported values, conversion method, return fields, formula, example mappings, and error handling. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes well beyond the schema. It explains the role of each leg, default pairings, how quote currencies are treated, and gives concrete examples that map natural language to parameter values. It also documents error conditions tied to parameter choices.

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 clear verb and resource: compare crypto asset prices across two exchanges, convert both legs to USD, and report premium. It differentiates itself from sibling tools by explicitly naming get_crypto_ticker and get_crypto_ohlcv as non-fit alternatives.

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

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

The description gives explicit when-to-use guidance with the kimchi premium example and maps natural-language phrases to concrete argument sets. It also states exclusions: 'Don't use for a single price (get_crypto_ticker) or history (get_crypto_ohlcv).' This fully routes the agent.

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, but that only covers side-effect safety. The description adds valuable behavioral context beyond annotations: KRW-to-USD conversion using FRED annual-average rates, the output row structure (per-metric, per-year with kr_krw, kr_usd, us_usd, ratio), the FX rates used, accounting-basis caveats, and the default metrics list. It does not explicitly say it makes network calls to multiple sources, but the source naming implies this adequately.

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-organized with a clear opening sentence, a concise args list, a return-format summary, concrete examples, and an exclusions/error section. It earns its length because it packs essential routing and usage information. Slightly lower than 5 because the args list partially duplicates the schema, but the duplication is acceptable for readability.

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 (cross-source data retrieval, FX conversion, multi-year, multi-metric comparison), the description covers nearly everything an agent needs: what it compares, what it returns, the identifiers it accepts, the annual-only limitation, and a fallback path to sibling search tools. The output schema exists, so the description correctly avoids restating return values field-by-field. It doesn't mention pagination or rate limits, but that is not critical for a comparison tool.

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

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

Schema coverage is 100%, so the schema already thoroughly documents all five parameters. The description adds meaningful semantics on top: it clarifies the accepted identifier formats for kr_company (name / stock code / corp_code) and us_company (ticker / name / CIK), gives concrete example values, and explains how response_format affects output. It also lists the default metrics, which are not fully enumerated in the schema. This goes beyond the schema's mechanical 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 specifies the action (compare), the two resources (KR and US company financials), the data sources (OpenDART, SEC EDGAR), accounting standards (K-IFRS, US-GAAP), and the FX conversion method (FRED DEXKOUS). It distinguishes itself from the individual get_dart_financials and get_edgar_financials siblings by focusing on cross-market comparison.

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

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

The description explicitly states what the tool is for, provides concrete input examples, and adds crucial exclusions: 'Don't use for quarterly data (annual only) or non-KR/US companies.' It also gives error handling guidance ('unknown company names suggest using search_dart_company / search_edgar_company first'), which helps an agent choose between this tool and the sibling search tools.

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

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

The annotations declare readOnlyHint: true, yet the description explicitly supports action='delete' and says the tool can 'delete' saved runs — a direct contradiction. Even though the description offers useful behavioral detail about rechecks, stored inputs, per-account retention and error behavior, the contradiction makes the safety profile untrustworthy and forces score 1.

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

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

Well-structured with clear sections: overview, rationale, Args, Returns, Use when, Errors, Notes. Though long, the content is information-dense and front-loaded with purpose; the main redundancy is the Args block partially duplicating the input schema.

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

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

The description covers the four actions, run_id requirements, response shapes, error behavior, per-account storage limits, and the recheck/drift use case. It also leverages the high-coverage input schema and output schema, making this a complete definition for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3 and the schema already documents all six parameters. The description restates the essentials for action, run_id and kind, but adds no new meaning beyond the schema and omits exposure of limit, trades and response_format in its Args section.

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 multi-verb statement — 'List, open, re-check or delete the backtest and factor runs saved for your account.' It names both the operations and the resource, and explicitly ties the stored runs to backtest_portfolio and analyze_factors, which clearly separates this tool from those execution-oriented 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?

An explicit 'Use when:' block lists three concrete scenarios: comparing prior runs, auditing trades from a backtest, and checking whether saved results still hold after nightly ingests. It stops short of naming alternatives or explaining when not to use the tool, so it lacks the full when/when-not contrast.

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

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

Annotations already indicate readOnlyHint and openWorldHint, and the description adds meaningful behavioral detail: no API key needed, ~5min caching, ascending time order, prices in QUOTE currency, and a described error path for unknown symbols. These go well beyond the annotation hints and make the tool's behavior predictable.

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 longer than the bare minimum but well-structured with Args, Returns, Examples, and Errors sections, and every section adds practical value. Some repetition of defaults from the schema exists, but the examples and error guidance justify the length.

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

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

The description is complete for a read-only data-fetching tool: it documents all six parameters, output shape, ordering, currency, caching, and error handling. Even with an output schema present, the explicit return structure and natural-language examples leave little room for an agent to misinvoke 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 baseline is 3. The description adds extra value through natural-language examples that map user intents to parameter values, explains the 'since' semantics as 'exchange returns candles from this date forward,' and clarifies response_format behavior. This is above baseline but the schema already documents most parameter meanings.

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: 'Fetch OHLCV candlestick data (open/high/low/close/volume) for a crypto pair.' It clearly distinguishes itself from the sibling get_crypto_ticker by explicitly saying it should not be used for a single current price. This makes the tool's purpose unambiguous.

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

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

The description gives explicit usage context through concrete natural-language-to-parameter examples and an explicit exclusion: 'Don't use for a single current price — use get_crypto_ticker.' It also notes exchange-specific behavior and common error cases, so an agent knows when and how to invoke 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 and openWorldHint=true, and the description adds useful behavioral context: no API key needed, ~10s caching, response fields, raw price values in quote currency, and known error modes (unknown symbol, geo-blocked exchange). No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then organized into clearly labeled sections: Args, Returns, Examples, Errors, Alternatives. Every section earns its place and the length is justified by the need to convey defaults, formatting, and pitfalls for a multi-exchange tool.

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

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

Given the tool has a full output schema and read-only annotations, the description is complete: it covers parameters, return structure, error handling, usage examples, and sibling differentiation. An agent has everything needed to invoke 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 baseline is 3. The description goes well beyond the schema by providing concrete symbol examples ('BTC/USDT', 'BTC/KRW'), explaining that upbit/bithumb use KRW quotes, noting the geo-block fallback to okx, and mapping natural-language phrases to parameter values in examples.

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: 'Fetch the current public ticker (last/bid/ask/24h stats) for a crypto trading pair on one exchange.' This clearly distinguishes it from sibling tools, and the later line explicitly says not to use it for candles/history or cross-exchange premium.

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 use cases ('current bitcoin price', 'BTC price in Korea') and explicit exclusions: 'Don't use for candles/history (get_crypto_ohlcv) or cross-exchange premium (compare_crypto_exchanges). This tells an agent exactly when to select this tool over alternatives.

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

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

Annotations already declare readOnlyHint: true, so the description's 'List' wording is consistent. The description adds valuable behavioral context beyond annotations: report names are in Korean, the filing body is NOT fetched and must be accessed via the returned URL, and the output includes pagination fields. It also discloses default date ranges and error behaviors.

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-organized with clear sections (main statement, Args, Returns, Examples, Use/alternative, Errors) and front-loads the core purpose. It is slightly verbose because some parameter details duplicate the input schema, but each section earns its place by providing examples, error guidance, and behavioral caveats.

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 (6 optional parameters, Korean filing types, pagination, and a specific output shape), the description is remarkably complete. It covers the return structure, the need to follow the URL separately, defaults, examples, and error handling, leaving no significant information gap for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by adding Korean translations for each disclosure type, the original DART pblntf_ty naming, and concrete examples for the corp parameter (e.g., '삼성전자', '005930'). It also clarifies defaults for date range and page/limit behavior, which adds meaningful semantics.

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: 'List corporate disclosure filings from DART', making the tool's purpose immediately clear. It also differentiates from siblings by explicitly naming get_dart_major_events and by listing the types of filings, so an agent can distinguish it from get_dart_financials or get_dart_insider_trades.

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 direct usage guidance: 'Use to track what a company disclosed' and explicitly routes keyword-filtered major events to get_dart_major_events. It also gives error-handling instructions (widen dates or drop filters for status 013; use search_dart_company for unknown companies), which clarifies when and how to adapt.

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 meaningful behavior: raw KRW amounts, EPS units, automatic fallback to separate statements, prior-year comparatives in annual reports, and exact error conditions. This gives the agent an accurate picture of side effects and edge cases.

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 a clear one-sentence purpose, then organized into Args, Returns, Examples, usage, and Errors sections. It is long, and some Args text duplicates the schema, but for a 5-parameter tool with complex return shape and error behavior, the structure keeps it navigable.

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 the data source, units, normalization, return structure, defaults, fallback behavior, error codes, and sibling-tool boundaries. With an output schema present and annotations already signaling read-only behavior, 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. The description adds incremental meaning: filing timing for the year parameter, automatic fs retry behavior, the 3-month nature of Q1 figures, and concrete example corp identifiers. This lifts it above baseline without being maximally 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?

States a specific verb and resource: 'Fetch financial statements of a Korean company from OpenDART' and normalize them to standard metrics. This makes the tool's role unmistakable and distinguishes it from sibling tools like get_edgar_financials and get_dart_filings.

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 for KR-listed company fundamentals. Don't use for US companies (get_edgar_financials) or for filings text (get_dart_filings).' It also tells the agent to run search_dart_company for unknown companies and how to recover from the 'no data' error. This is model routing guidance.

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

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

Annotations already mark the tool read-only, and the description builds on this by adding key behavioral facts: buy/sell is defined by the sign of the share change, KR reports contain no transaction price, filings are delayed ~5 business days, and summary totals cover the entire fetched set regardless of filter. This goes well beyond the annotations and schema.

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

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

The description is long but densely informative, with every section earning its place: source, sign semantics, args, return structure, limitations, examples, routing, and error handling. It is front-loaded with purpose and a clear definition of buy/sell, then uses structured sections for details.

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?

Even with a rich output schema present, the description includes the return structure, filter semantics, examples, known limitations (no price, filing lag), and error paths. An agent has everything needed to select, invoke, and interpret this tool correctly without additional context.

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

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

The schema already documents all parameters at 100% coverage, so the baseline is 3. The description adds extra value by explaining the sign convention behind tx_type, providing concrete examples for company resolution, and emphasizing the sentiment meaning of insider buying. This lifts it above baseline, though it does repeat some schema content.

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

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

The description states a specific action ('get insider transactions for a listed KR company'), identifies the exact source ('DART elestock'), and explicitly aligns it with SEC Form 4. It names sibling tools for US insiders and institutional holdings, so the tool is clearly differentiated from get_edgar_insider_trades and get_edgar_13f.

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

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

The description provides explicit 'Use when' guidance, names the alternative for US insiders, and explains that unknown companies should be resolved via search_dart_company. It also clarifies that a filter with no matches returns count 0, not an error, which prevents incorrect error handling.

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?

Even though annotations already mark the tool as read-only and open-world, the description adds substantial behavioral detail: client-side filtering over the most recent 100 events, default date range of 180 days, how total is computed when kinds is supplied, and specific DART error status handling. No contradiction exists between the description and 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 with Args, Returns, Examples, Use, and Errors sections, and every sentence carries decision-relevant information. The main purpose is front-loaded, and the length is justified by the density of useful detail rather than 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?

The description covers filtering scope, defaults, client-side behavior, return shape, error conditions, and sibling tool routing. Since an output schema exists, not repeating return value details is acceptable; the description is complete for a read-only filtered retrieval tool.

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

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

Schema description coverage is 100%, and the description still adds meaningful semantics beyond the schema: accepted corp formats plus omitting it for market-wide events, JavaScript regex behavior applied client-side, the 100-event scanning window, and illustrative examples for kinds. This materially helps an agent choose and format arguments correctly.

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: 'List major-event disclosures (주요사항보고서, DART type B)' and enumerates concrete event categories such as capital increases, mergers, and treasury stock. It also differentiates itself from get_dart_filings by scoping this tool to major events rather than all filing categories.

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

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

The description explicitly states when to use this tool: 'Use for event-driven screening.' It also names the alternative, get_dart_filings, for all filing categories, and the error section routes unknown companies to search_dart_company. The examples clarify both company-specific and market-wide use cases.

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

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

Even with readOnlyHint=true already in annotations, the description adds meaningful behavioral context: row counts are 'cached 5 minutes', the database is a local SQLite store, and the error 'database has not been built yet' is explained as the ingest pipeline not having run. This goes well beyond the annotation and prepares the agent for real-world behavior.

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

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

The description is long but tightly organized with clear sections (Args, Returns, Key objects, Examples, Use when, Errors). Every section earns its place: the schema details in 'Key objects' are essential for understanding the database, and the error note prevents confusion. It is front-loaded with the core purpose.

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

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

Given the complexity of a database schema tool, the description is remarkably complete: it explains key tables and fields, identifies the preferred views, provides example usage, and covers failure modes. The presence of an output schema further reduces the need to explain return values, but the description already does so.

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, and the description explicitly states 'Args: (none)', eliminating ambiguity. Per the baseline for zero-parameter tools, this is a 4. The return-value breakdown is also present, helping the agent understand how the tool's output will be structured.

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 ('Inspect') and resource ('schema of the local finbridge database') and enumerates exactly what is returned: tables, views, columns, row counts, example queries. It clearly distinguishes itself from siblings by explicitly disclaiming live market data and pointing to query_db, making it easy to tell apart.

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

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

The description provides explicit usage conditions: 'Use when: preparing a query_db, or checking ingest coverage.' It also gives a direct exclusion: 'Don't use for live market data (use the dart_/edgar_/fred_/crypto_ tools).' This is exemplary when/when-not guidance.

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

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

Annotations already declare readOnlyHint, so the description needn't restate that; instead it adds valuable behavioral context: refresh cadence ('nightly + intraday for KR'), materiality defaults, override chains (forms overrides material_only, from/to overrides days), return shape, and 'empty result is not an error (count 0)'. It also notes metadata-only content and link to source URLs, which is more than the annotations carry.

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

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

The description is long but well-structured, front-loading the core purpose before the Args list, and each section (Returns, Examples, Use when, Notices) earns its place. The only minor deduction is rhetorical filler like 'positioned as a faster-than-news primary source' and boilerplate 'Not investment advice', which are not strictly needed.

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 9 parameters, an output schema, and many siblings, the description covers everything needed to invoke it correctly: argument semantics, defaults, overrides, return fields, examples, error behavior, and explicit routing guidance. It is hard to imagine an agent being confused after reading 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?

Although schema coverage is 100%, the description enriches the params meaningfully: market maps 'kr' to DART and 'us' to EDGAR; material_only defines what counts as material (8-K / KR type-B); forms gives examples ['10-K','8-K'] / ['A','B']; from/to and days behavior with override semantics are made explicit. The usage examples tie params to real use cases.

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 'Recent regulatory disclosures from the local finbridge database' and immediately narrows to the filings table with a specific default scope (material filings: US 8-K and KR 주요사항보고서). This clearly distinguishes it from siblings like get_dart_filings/get_edgar_filings, and the 'Don't use for filing BODIES' phrase further differentiates it.

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 has an explicit 'Use when' section naming catalyst scanning and single-company filing review, plus explicit 'Don't use for' exclusions pointing to alternatives (get_dart_financials, get_edgar_financials, query_db). This tells an agent exactly when to pick this tool vs. others.

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 mark this read-only and open-world, and the description adds substantial behavioral context: CUSIP-level aggregation/summing, 45-day filing lag, value normalization from thousands to whole USD, coverage limits (long US-listed 13(f) securities only), and specific ToolError cases. 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 long but logically structured into labeled sections (Args, Returns, Examples, Use when, Don't use, Caveats, Errors), making it easy for an agent to scan. The only minor issue is some repetition of the ticker-resolution warning, though it is defensible emphasis for a common failure mode.

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 one required parameter, rich annotations, and an output schema, the description covers invocation, parameter semantics, examples, failure modes, and data caveats comprehensively. Nothing an agent needs to decide whether 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%, and the description still adds real value: filer gets examples plus the critical caveat that issuer tickers will not resolve; top gets its 1-50 range and the behavior of capping QoQ changes; response_format gets clarity on markdown vs json. This far exceeds the baseline.

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

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

The description opens with a specific verb and resource: 'Latest institutional-manager holdings from a SEC Form 13F-HR filing, aggregated by security with quarter-over-quarter changes.' It also explicitly distinguishes the tool's filer-centric scope from a reverse 'who owns <ticker>?' lookup, clearly separating it from sibling EDGAR 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?

Provides explicit 'Use when' and 'Don't use for' sections, including a direct pointer to get_edgar_insider_trades / Form 4 as the alternative for insider trades. It also lists concrete exclusions (Korean holdings, intra-quarter/real-time positions) and notes the unsupported reverse lookup.

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 annotations already declare readOnlyHint=true and openWorldHint=true, and the description reinforces this by stating it does NOT download filing contents and that the caller must fetch the returned URL. It also discloses meaningful behavior beyond the schema: exact-match case-insensitive form filtering, a ~1000-filing window, and 8-K items. These details add real 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?

The description is well-structured with labeled sections (Args, Returns, Use when, Don't use, Errors) and front-loads the most important behavioral constraint—no content download—immediately. Examples and error guidance justify the length; 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?

For a read-only list tool with a rich output schema, the description covers the return shape, parameter constraints, usage boundaries, and error recovery. It is complete enough for an agent to call the tool correctly and interpret results without additional 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 100%, so the baseline is 3, but the description adds useful semantics beyond the schema: the exact-match and case-insensitive nature of forms, the ~1000-filing window implication, and the practical interpretation of company as ticker/name/CIK with examples like 'BRK-B' or 'BRK.B'. This lifts it above baseline.

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

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

The description opens with a specific verb and resource: 'List a US company's recent SEC filings' from the EDGAR submissions index. It clearly distinguishes itself from sibling tools by stating it returns metadata and document URLs only, not contents, and by naming Korean disclosures and full-text search as exclusions.

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 when' and 'Don't use for' sections name the exact conditions and alternatives, including get_dart_filings for Korean disclosures and full-text search for all companies. It also gives error guidance to use search_edgar_company for unknown companies, which fully routes the agent to the correct 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?

The description goes well beyond the readOnlyHint annotation by disclosing that values are raw USD, eps_diluted is per share, Q4 is not reported separately, periods are most-recent first, and fiscal_year equals the calendar year of the period end date. It also documents error behavior for unknown companies and unsupported filers, adding substantial behavioral context beyond what annotations provide.

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

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

The description is well-structured with clear sections: summary, Args, Returns, Examples, Use when, and Errors. It is longer than necessary because the Args section repeats schema information, but every section serves a distinct purpose and the critical usage guidance is 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 description is complete for a read-only financial data tool: it covers input semantics, output shape, edge cases (Q4 missing, foreign issuers, unknown companies), alternative tools, and usage contexts. The output schema is also summarized in the Returns section, so an agent has enough information to invoke and interpret 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 the baseline is 3. The description adds value through concrete examples (e.g., 'AAPL', 'Microsoft', '789019'), clarifications like discrete Q1-Q3 from 10-Qs, and a natural-language mapping example. There is some duplication of schema descriptions in the Args block, but the additions improve parameter understanding.

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

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

The description states a specific verb and resource: it 'Normalized annual (10-K) or quarterly (10-Q) financial statements for a US company, from SEC EDGAR XBRL company facts (US-GAAP).' It clearly distinguishes itself from siblings like get_dart_financials and get_stock_prices by specifying US-GAAP fundamentals from SEC filings.

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 'Use when: you need US-GAAP fundamentals for a US-listed company' and 'Don't use for: Korean companies (get_dart_financials), stock prices, or IFRS 20-F foreign private issuers (not supported).' This names alternatives and exclusion conditions, giving an agent clear routing guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavioral details: summary totals cover the full window regardless of filter, value is calculated as shares x price, unparseable XMLs are skipped and counted in notes, and empty filtered results return count 0 rather than error. This is rich, non-obvious behavior that agents need.

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

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

The description is long but every section earns its place: purpose, args, return shape, transaction codes, examples, use/don't-use, and error behavior. The structure is front-loaded with the core purpose and uses compact labeled sections for quick 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 complex SEC-filings tool with three parameters, an output schema, and multiple sibling tools, the description covers all critical contexts: company identification formats, filtering semantics, edge cases, error handling, and exclusions. Nothing essential is left for the agent to infer.

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 value: it explains the meaning of transaction codes (P, S, M, F, A, G), clarifies that summary aggregates span the whole window despite tx_type filtering, and provides example inputs like 'AAPL' and 'NVDA'. This goes beyond the schema's field-level 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 opens with a specific verb and resource: 'Latest insider transactions for a US company, parsed from SEC Form 4 filings' plus a buy-vs-sell summary and filter. It clearly identifies the SEC Form 4 domain, distinguishes itself from DART-based insider trades, and explicitly says 'Don't use for: ... Korean companies'.

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

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

The description provides explicit when-to-use ('monitoring insider buy/sell activity... for a US-listed company') and when-not-to-use guidance, naming the sibling alternative 'get_edgar_13f' for institutional holdings. It also gives concrete query examples mapping natural language to parameters.

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 mark readOnlyHint=true and openWorldHint=true, and the description adds meaningful behavioral details: frequency aggregation 'cannot be finer than the native frequency', 'value is null where FRED reports .', the latest-N semantics of limit, and an API-key error hint. 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?

The description is long but every section earns its place: one-line purpose, parameter semantics, return shape, examples, and error guidance. It is clearly structured with labels, making it easy to scan, and the examples are high-value rather than 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 7-parameter tool with one required parameter, this description fully equips an agent to invoke it correctly: it covers parameter combinations, return format, null handling, error behavior, and relationship to the FRED API key. Nothing necessary for correct invocation 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%, but the description adds substantial value: frequency constraint versus native frequency, limit behavior in and out of a date range, unit transformation choices with examples, and realistic series IDs. The examples map entire user intents to parameter combinations, which goes far 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: 'Fetch observations (time series data points) for a FRED series', with optional modifiers. It clearly distinguishes from series discovery by saying 'Don't use for series discovery — use search_fred_series first', and the examples reinforce the observation-fetching purpose.

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 the agent when not to use it ('Don't use for series discovery — use search_fred_series first') and gives four concrete natural-language-to-parameter examples. It also explains the behavior of limit with and without a date range, which is exactly the kind of usage nuance an agent 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?

Annotations already mark it read-only and open-world, and the description adds meaningful behavior: 'value' is the latest non-null observation with 'prev' being the one before it, partial failures degrade to 'notes' rather than failing the whole snapshot, and missing FRED_API_KEY surfaces a hint. This is more than the annotations alone provide.

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

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

The description is dense but well-organized into Args, Returns, Examples, and Errors, with the core purpose front-loaded. Every section contributes operational knowledge rather than restating the name or schema.

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

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

For a one-parameter, read-only snapshot tool with an output schema, the description is complete: it defines the return shape, explains degraded behavior, names the alternative for historical/flexible queries, and covers the API-key prerequisite. Nothing essential 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 single set parameter already has an enum and default, so the baseline is 3; the description adds real value by itemizing exactly which indicators each set contains and clarifying transformations such as CPI YoY %. This makes choosing the correct set much easier.

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: 'Fetch a predefined set of key US macro indicators from FRED in one call' and enumerates exact series by set. It clearly distinguishes this snapshot tool from get_fred_series by emphasizing predefinition and single-call behavior.

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 selection guidance: 'Don't use for historical analysis or non-listed series — use get_fred_series instead,' plus natural-language examples that map to set values. This tells an agent exactly when to invoke this tool versus its closest sibling.

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

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

Beyond the readOnlyHint annotation, the description richly discloses behavior: market-cap proximity ranking, same-market prioritization, fallback to size peers when no classification exists, the informational segment-revenue split, error behavior returning candidate lists, and currency caveats for cross-market comparisons. None of this contradicts the annotations.

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

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

The description is long but earns its length for a tool with 6 parameters, 4 markets, and nuanced ranking logic. It is well-structured with Args, Returns, Examples, Use when, Notes, and Errors sections, and the core purpose is front-loaded before the parameter detail.

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 a description that details the return object's fields, ranking bases, segment payload, and error behavior, the tool is fully specified. It covers edge cases like missing classification, geographic segment names, and cross-market currency approximation, so an agent has everything needed to call it correctly.

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

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

Although schema coverage is 100%, the description adds substantial meaning: accepted company identifier formats per market, the market disambiguation rationale, default behavior for same_market_only, and a detailed explanation of the 'segments' rank option including cosine similarity and tie-breaking. Examples map concrete values to expected behavior.

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: 'Comparison set for one company across KR / US / TW / JP: the company plus its closest peers.' It clearly defines the tool's scope and distinguishes it from siblings by explicitly naming what it is not for, such as strategy screens and full financial 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?

The description gives direct usage guidance: 'Use when: building a comparison table or choosing competitors for a financial comparison. Don't use for strategy screens (screen_*) or for full financial statements (get_dart_financials / get_edgar_financials).' It also explains fallback behavior and disambiguation contexts, leaving no ambiguity about when to invoke this 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?

The description reveals live ccxt quotes and a FRED DEXKOUS conversion, which are open-world external dependencies, but the annotations declare openWorldHint=false. This contradicts the annotation and undermines the agent's assumptions about determinism and external data access. Per rubric, an annotation contradiction drops this to 1.

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

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

Three sentences, each earning its place: scope in sentence one, valuation sources in sentence two, aggregation/currency behavior in sentence three. It is front-loaded and free of filler.

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

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

Given a no-argument tool with an output schema, the description covers asset coverage, per-asset valuation method, return/allocation outputs, and currency aggregation. Nothing an agent needs to select and invoke it correctly is missing, aside from the annotation inconsistency already penalized.

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 are zero parameters, so the schema already fully documents the input side. The description doesn't need to add parameter semantics, and it doesn't introduce any misleading input expectations.

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: 'Return the user's whole portfolio,' then enumerates asset classes and outputs such as valuation, return, and allocation. This clearly distinguishes it from sibling get_* tools as the aggregate portfolio view rather than a market/ticker/screener tool.

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

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

The use case is implied (obtain an overall portfolio snapshot), but the description never tells the agent when to prefer this over siblings like get_stock_prices or import_portfolio, and it names no exclusions. With 35 siblings, explicit routing guidance would strengthen 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 only convey read-only behavior, but the description discloses much more: data is populated by nightly ingest jobs, rows are newest-first, market coverage depends on redistribution rights, the free plan trims history and adds a plan_limit field, and errors include market-specific hints. All of this is consistent with readOnlyHint=true; there is no contradiction.

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

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

The description is long but tightly organized into front-loaded summary, market coverage, args, returns, examples, usage guidance, and errors. Each section carries necessary information for a complex multi-market tool, and the opening sentence immediately communicates the core function.

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

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

The description covers the full calling context: data availability per market, identifier resolution rules, plan-based limitations, response structure including truncation, and error behavior for unknown or unsupported companies. Given the tool's complexity, the description leaves little for the agent to infer.

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?

Although the schema already describes all five parameters, the description adds significant meaning: company resolution priority with market-specific examples, inclusive date range semantics, the 1-500 limit with its default and plan-trimming behavior, and response_format output differences. The examples further clarify real usage patterns.

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 first sentence states a specific action and resource: getting daily OHLCV price history from the local finbridge database. It further differentiates itself from siblings by explicitly ruling out real-time quotes and crypto, naming get_crypto_ohlcv as the 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?

The 'Use when' and 'Don't use' sections give explicit guidance: use it for historical closes/volumes for charting or return calculations, and avoid it for real-time quotes or crypto. The market-coverage section also tells agents when a request for Japanese or EU companies will fail, enabling routing to other 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 only declare readOnlyHint and openWorldHint; the description goes far beyond by explaining data origin and refresh cadence (nightly ingest), on-demand recomputation not stored, corporate-action adjustment caveats, US history start dates, and expected error cases. These behaviors materially affect interpretation of returned data.

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

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

The description is long but appropriately so for a tool with many indicators and caveats. The core purpose is front-loaded, and the headed sections (Indicators, Args, Returns, Examples, Use when, Notes, Errors) are dense with actionable information. 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 complex tool, this description covers everything needed to call it correctly: parameters, return shape, examples, alternatives, error modes, data caveats, and market-data disclaimer. An agent can confidently decide to invoke it and interpret results from the description alone.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: company resolution order (exact ticker > 6-digit code > exact name > partial name), the exact recompute behavior of history, and the response_format effect. These details are not present in the input schema alone.

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

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

States a specific verb and resource: fetching the latest technical-indicator snapshot for a single KR or US company. It enumerates the indicators covered, distinguishes single-company scope from screening tools, and the title/name are not merely restated.

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 when to use the tool ('reading one company's momentum/trend/overbought-oversold state, or charting an indicator series') and when not to ('Don't use to rank many companies (use screen_technical) or for live intraday quotes (use the live-source tools)'). It names sibling tools and gives exclusion conditions.

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

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

Annotations declare readOnlyHint=true, which is consistent with 'Get', but the description adds substantial behavioral context: share-count derivation differences between KR and US, PER fallback logic, null-ratio handling, nightly ingest job, no FX conversion, K-IFRS vs US-GAAP caveats, and snapshot-not-real-time status. These are exactly the kind of non-obvious behaviors an agent needs to interpret results correctly.

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

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

The description is long but extremely well structured with clear sections: Args, Returns, Examples, Caveats, Use when, and Errors. The core purpose and metrics are front-loaded, and every paragraph adds distinct value. The examples and error explanations earn their place in a tool with this much computational nuance.

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

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

Given the tool's complexity, the description covers all needed context: supported identifiers, return object shape, calculation rules, fallback behavior, error cases, use vs. non-use cases, and accounting/FX caveats. An agent can determine whether to call this tool, how to pass parameters, and how to interpret the result without external 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?

Although the input schema already covers both parameters 100%, the description goes further: it explains company resolution priority ('exact ticker > 6-digit code > exact name > partial name'), the candidate-list error behavior for ambiguous partial matches, the response_format default, and the meaning of ratio units (percent). This materially helps an agent form correct argument values.

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

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

The description opens with a specific verb and resource: 'Get the latest valuation snapshot for one KR or US company from the local finbridge database.' It enumerates the exact metrics returned (market cap, PER, PBR, PSR, ROE, debt ratio, CAGRs) and explicitly contrasts itself with raw-statement tools like get_dart_financials/get_edgar_financials, so there is no ambiguity about what this tool does.

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 'Use when' section explicitly states the intended scenarios: 'assessing one company's valuation/quality at a glance, or comparing it to its own market.' It also names exclusions and alternatives: 'Don't use for many-company ranking (use screen_companies / query_db) or raw statements (get_dart_financials / get_edgar_financials).' This gives an agent clear routing criteria.

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 mark destructiveHint=true and readOnlyHint=false, and the description adds substantial behavioral context beyond that: merge/replace semantics, live ccxt quotes for crypto and gold, direct-value storage for cash/physical/unsupported ETFs, and automatic watchlist registration. There is no contradiction with the annotations.

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

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

The description is long but dense: each sentence covers a distinct asset category, pricing path, or caveat. It is front-loaded with the core purpose and then layers asset-type handling and parameter guidance. Minor restructuring could improve scannability, but there is little 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?

For a complex import tool, the description covers the essential behavioral surface: accepted asset types, database matching, live quote behavior, direct-value fallback, replace/merge semantics, category label handling, and the watchlist side effect. An output schema exists and annotations cover the destructive nature, so no major missing context remains.

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

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

Schema description coverage is 100%, so the baseline is met, but the description adds cross-parameter guidance that the schema alone does not provide: when to pass asset_class, when to pass value directly instead of relying on pricing, and how price_symbol/unit interact for PAXG and TLT-style symbols. This adds meaningful decision guidance for the holdings array.

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: 'Register holdings read from a brokerage (MTS/HTS) screenshot or an asset table into the user's portfolio.' It clearly distinguishes itself from siblings like add_to_watchlist and get_portfolio by emphasizing bulk portfolio registration and the automatic watchlist side effect for listed 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?

The description gives strong usage context: it should be used when importing holdings from screenshots or tables, covering stocks, cash, crypto, and physical assets. It does not explicitly name alternatives or state when not to use it, but the input-source framing and write behavior separate it from the read-only and screening 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?

The description goes far beyond the readOnlyHint annotation by disclosing the exact execution model: the query is wrapped as SELECT * FROM (<sql>) LIMIT <limit> on a read-only connection, and forbidden constructs such as PRAGMA, multiple statements, and DDL keywords are rejected. It also explains the truncated flag semantics and error behavior, giving the agent a realistic picture of outcomes before invoking.

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

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

The description is long but well-structured with clear sections (Args, Returns, Examples, Use when, Errors), and every part earns its place for a tool with nontrivial constraints. Core rules are front-loaded before parameters and examples, and no filler or tautological phrasing is present.

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 SQL-execution tool, the description is remarkably complete: it covers accepted syntax, rejected patterns, result shape, row limits, error behavior, example queries, and alternative tools. With an output schema and readOnlyHint already present, nothing essential is missing for an agent to select and invoke this 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 the baseline is 3, but the description adds value through concrete examples that clarify how sql, limit, and response_format work together, including real view names and join patterns. It also adds nuances the schema lacks, such as tolerating a single trailing ';' and noting which data sources and date ranges are available.

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: 'Run a single read-only SELECT query against the local finbridge database,' and names the data domains (KR/US fundamentals, filings, daily prices). It clearly distinguishes itself from siblings by emphasizing the custom SQL/read-only scope, so an agent can tell it apart from screen_companies or get_stock_prices.

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

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

The description explicitly states when to use it ('custom aggregation/joins over ingested data that screen_companies cannot express') and when not to use it ('Don't use for anything that writes... or for live quotes'), even directing to 'live-source tools' as alternatives. It also provides the error-recovery hint to call get_db_schema first for unknown tables.

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 provide readOnlyHint=true and openWorldHint=false, so the description carries the behavioral burden. It discloses nightly snapshot timing, NULL-metric exclusion, accounting-standard differences, dividend/corporate-action caveats, and the empty-result-not-error behavior—all beyond what annotations convey.

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

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

The description is well-structured with clear sections: overview, criteria, args, returns, examples, usage, notes, and errors. It is long, but the complexity of a 13-parameter screener justifies most of it; the I/M omission is repeated in both the intro and notes, adding minor redundancy.

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

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

The description covers the full decision surface: filter semantics, return shape, example calls, market-specific caveats, known error messages, and data freshness limitations. With an output schema present and all parameters documented, nothing needed to call this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial value: it maps each parameter to a CAN SLIM criterion, explains quarter-code comparisons, gives examples, and specifies units. However, it incorrectly states that market's default is 'all' while the schema says the default is 'kr', which is a real reliability concern.

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: it "screens KR and/or US stocks" against the CAN SLIM checklist using two named snapshots. It also distinguishes itself from siblings by explicitly saying not to use it for get_valuation, screen_minervini, or raw statement 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 has an explicit 'Use when' section naming the exact scenario and an explicit 'Don't use for' section that names four sibling tools. It also explains why CAN SLIM's I and M criteria are intentionally not screened, preventing the agent from expecting them.

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 state readOnlyHint=true, but the description goes far beyond that: only annual rows (quarter=0) are considered, amounts are in each filer's reporting currency, Taiwan has only the latest period, Europe has specific data-coverage gaps, period fallback behavior is explained, market='all' never mixes periods, and empty results are not errors. None of this contradicts the annotations.

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

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

The description is long, but it is organized into labeled, decision-relevant sections: market scope, coverage caveats, 'eu' semantics, period fallback, args, metrics, returns, examples, use-when, and errors. It is front-loaded with the core purpose and every section earns its place given the complexity of five markets and several data-quality nuances.

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

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

The description covers market scope, data quality, currency handling, duplicates, fallback behavior, parameter semantics, metric definitions, return shape, examples, when-not-to-use guidance, and error messages. It even explains the reasoning behind behaviors such as why market='all' refuses period fallback, which an agent needs to make correct calls.

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?

Even though schema coverage is 100%, the description adds essential meaning beyond the schema: formulas for derived ratios, the percent convention for ratios, market-dependent absolute-value caveats, fiscal_year omission meaning 'latest annual report', filters being ANDed, max and default values, the period field, and concrete examples. This substantially enriches the raw schema definitions.

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: 'Screen companies across five markets on annual fundamentals stored in the local finbridge database.' It names all five markets and the regulatory sources, and later explicitly distinguishes itself from query_db, get_dart_financials, and get_edgar_financials by saying it is not for single-company statement detail. This makes the tool clearly distinguishable from sibling screening and financial-statement tools.

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

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

The description contains an explicit 'Use when: ranking or filtering many companies at once' and a 'Don't use for a single known company's statement detail' branch with named alternatives. It also gives practical guidance on when to screen one market at a time, why market='all' can duplicate cross-listed companies, and why cross-market screens work best with ratio 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?

Despite readOnlyHint=true and openWorldHint=false already signaling safety, the description adds material behavioral context: KR vs US data availability, null NAV/AUM for US, price-return vs total-return semantics, same-day premium computation, AUM currency caveat, and the one-calendar-year pinning of total_return_pct. It also documents the 'database has not been built yet' error and that empty results are not an error. No annotation contradiction exists.

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 with warnings, per-market coverage, args, examples, and use-when sections, and it front-loads the core purpose. It is, however, longer than strictly necessary: the 'Args' and 'Returns' sections largely repeat information already present in the input and output schemas, so a few sentences add redundancy rather than new signal.

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 definition is complete for a complex, 13-parameter screening tool: it covers market-specific behavior, result semantics, sort options, error cases, and provides four representative invocation examples. The output schema already specifies the return shape, and the description supplements with caveats an agent needs to avoid producing misleading tables.

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

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

Schema coverage is 100%, but the description goes well beyond the schema: it gives a concrete min_aum conversion example (100000000000 = 1,000억), explains that premium_pct is same-day close/NAV-1, shows how index_contains finds 'TR' or '코스피' trackers, and clarifies that total_return_year can be omitted for the best-covered year. These are semantics an agent could not derive from property descriptions alone.

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

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

The description opens with a concrete verb and resource: 'Screen exchange-traded funds in the local finbridge database' and immediately names the differentiating fields (NAV premium, AUM, index, momentum, total return). It also distinguishes itself from screen_companies, so an agent can discriminate among sibling screening tools without inspecting their 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?

The 'Use when' section states exactly when to call it ('choosing or comparing funds') and explicitly says not to use it for stocks (screen_companies) or single-fund price history (get_stock_prices). The coverage-per-market and excluded-funds notes further narrow when this tool is appropriate.

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 evaluation happens on the nightly indicators_latest snapshot, that prices are corporate-action-adjusted but not dividend-adjusted, that US history has known shallow periods, and that an empty result is not an error. It also explains the 'database has not been built yet' error case.

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

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

The description is long but well-structured with labeled sections: approximation, conditions, args, returns, examples, usage, notes, and errors. It front-loads the core purpose and caveats. The Args section repeats some schema content, but every other section earns its place.

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

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

Given 10 parameters, zero required fields, a complex screening methodology, and an output schema, the description is remarkably complete. It defines the exact screening conditions, return fields, data caveats, use cases, alternatives, and error semantics. An agent has all the context needed to invoke and interpret this 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 schema already covers all 10 parameters with 100% description coverage, so the baseline is 3. The description adds meaning through rationale ('Kell trades leaders' for rs_min), concrete examples (e.g., min_vol_avg20: 500000, min_price 5000 KRW), and clarification of sort/format choices. It comfortably exceeds baseline but partially duplicates 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 opens with a specific verb and resource: 'Screen KR, US and/or TW stocks for an Oliver Kell "Cycle of Price Action" long setup.' It also distinguishes itself from siblings in the 'Use when' paragraph, explicitly routing agents to screen_minervini for the 8-point trend template and screen_technical for arbitrary technicals.

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 states when to use the tool — 'shortlisting momentum leaders riding short-term EMAs (Kell style, approximate)' — and when not to, warning not to treat a pass as a Kell 'buy'. It names concrete alternatives and gives worked examples for US and KR usage.

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 substantial behavioral context: VCP detection is an 'APPROXIMATION (heuristic swing/contraction count, not a discretionary chart read)', prices are 'adjusted for corporate actions but not dividends', US history has known start dates that affect long-window figures, and RS percentile interpretation is explained. It even clarifies that an empty result is not an error and what a specific database error message means.

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

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

The description is long but justified by the tool's complexity (12 parameters, 8 screening criteria, multiple markets). It is well-structured with clear sections: criteria list, arguments, return shape, examples, use-when, notes, errors. It drops one point because the Arguments section partially repeats schema descriptions and the 8-criteria list, while valuable, adds substantial length; a slightly tighter version would be even more concise.

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

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

The description is complete for a complex screening tool: it covers the data source snapshot, all filter semantics, return fields, sorting options, example invocations, concrete use/when-not-use guidance, data caveats (dividends, US history start), and error conditions. The output schema likely exists, but the description also spells out the expected return object, leaving the agent with everything needed to call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context beyond the schema: it explains why each parameter matters (e.g., 'min_price' avoids penny stocks with example values for US$ and KRW), how 'near_high_pct' relates to tightness, and that 'rs_min' has a Minervini preference for higher values. While the field-level descriptions in the schema are already strong, the tool description enriches them with rationale and examples.

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: 'Screen KR, US and/or TW stocks that pass Mark Minervini's 8-point Trend Template.' It explicitly names the methodology, the underlying data snapshot, and the return focus ('stage-2 uptrend leaders'), making the tool's purpose unambiguous and easily distinguished from siblings like screen_technical or get_technicals.

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 'Use when' section states exactly when to apply the tool: 'finding stage-2 momentum leaders (Minervini/CAN SLIM style).' It also gives explicit exclusions: 'Don't use for a single stock's detail (get_technicals), fundamentals (screen_companies/get_valuation), or arbitrary technical signals (screen_technical).' This gives the agent clear routing guidance.

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

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

Annotations give readOnlyHint=true, and the description goes beyond this by disclosing that this is an approximation with false positives and misses, that prices are corporate-action-adjusted but not dividend-adjusted, that US history starts 2023-03-28, and that empty results should not be treated as errors. It also explains the 'database has not been built yet' error condition.

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

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

The description is front-loaded with purpose, uses clear section headers, and is scannable with bullets. However, the Args section largely duplicates the input schema, and the approximation caveat is repeated several times. These are minor, since each section still 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?

For a 10-parameter, 0-required-parameter tool with an output schema, the description is complete: it documents all strategy conditions, parameter semantics, output shape, examples, data quirks, error behavior, and when to route to alternative tools. There is no meaningful operational gap for an agent deciding how to invoke this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by mapping parameters to the strategy conditions, giving concrete examples (e.g., min_price=10 for US$, 5000 for KRW; min_vol_avg20=500000), and showing how arguments combine in practice. It loses a point because the Args block mostly restates schema defaults and the market arg listing omits the 'tw' enum option that the schema supports.

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: 'Screen KR, US and/or TW stocks for a Marty Schwartz short-term momentum setup.' It names the strategy logic, the data snapshot, and the approximation nature. It also disambiguates itself from siblings by directing to screen_minervini for the trend template and screen_kell for EMA-support leaders.

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

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

The description provides an explicit 'Use when' section: short-listing short-term momentum names on a 10-EMA green light. It gives concrete exclusions ('Don't treat a pass as a Schwartz buy') and names which siblings to use instead for other strategies. It also includes practical examples for US liquid names and tight KR setups.

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 readOnlyHint already declaring the operation safe, the description adds substantial behavioral context: fixed whitelists mapped to SQL predicates with parameter-bound thresholds, nightly refresh behavior, corporate-action adjustments, US data history limits, empty-result semantics, and known error strings. This far exceeds what annotations alone provide.

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

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

The description is long but highly structured and information-dense: Args, RS explanation, Returns, Examples, Use when, Notes, and Errors each serve a distinct purpose. It is front-loaded with the core purpose and safety property, and 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 tool with 8 parameters, an output schema, and several siblings, the description covers all relevant context: market scope, signal semantics, sorting, filtering, output format, use cases, exclusions, known limitations, and error behavior. An agent has everything needed to invoke it correctly without further research.

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?

Although the schema already has high coverage, the description enriches every parameter group: it defines signal thresholds, explains sort-key semantics, and describes rs_pctile/rs_120d in practical terms. The worked examples also clarify parameter combinations and expected usage patterns beyond the raw 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 clearly states the tool's action and resource: screening companies by technical signals on the latest indicator snapshots. It distinguishes itself from relevant siblings by explicitly naming get_technicals for one-company detail and screen_companies for fundamentals. The action and scope are specific and unambiguous.

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

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

The 'Use when' section explicitly says to use this tool for ranking/filtering many companies by momentum or trend signals, and directly tells the agent not to use it for one company's detail or fundamentals, even naming the alternatives. This gives clear selection criteria without requiring 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 and openWorldHint, so the description does not need to restate safety. It adds valuable behavior not in the annotations: matching priority, stock_code being null for unlisted companies, the ~90k unlisted entity scope, and error/edge-case behavior including no-match returning count 0. This exceeds baseline transparency without contradicting the annotations.

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

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

Although the description is lengthy, every section earns its place: Args, Returns, Match priority, Examples, Use-when, and Errors. The structure is scannable with clear labels, and the most important scoping information is front-loaded in the first sentence.

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

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

The description is complete for an agent to invoke the tool correctly: it covers input formats, output shape, match disambiguation, example usage, sibling routing, and error behavior. The presence of an output schema does not leave any critical gap, and the listed_only behavior is fully explained.

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 parameters are already documented. The description goes beyond the schema by clarifying that query accepts a name, 6-digit KRX stock code, or 8-digit corp_code, that Korean names work best, that unlisted results have null stock_code, and that match priority favors exact codes. This adds real semantic value to the agent's understanding.

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

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

The description states a specific verb ('Search') and resource ('companies registered with DART, South Korea's corporate disclosure system'), and clearly distinguishes its search identity from the US-focused sibling search_edgar_company. It also explains the tool's key output, the corp_code required by other dart_* tools, making its role in the tool family immediately obvious.

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

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

The description explicitly says when to use the tool ('when you need a corp_code or must disambiguate similar names'), and when not to use it ('Don't use for US companies (use search_edgar_company)'). It also gives practical guidance on query forms, listing scope, and match priority, leaving no ambiguity about invocation 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?

Beyond the annotations (readOnlyHint, openWorldHint), the description discloses meaningful behavior: match ranking order, error handling for no matches, and the constraint that only SEC registrants with a listed ticker are searchable. These details let an agent predict edge cases. No contradiction with annotations exists.

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 into Args, Returns, Examples, Use when, Don't use, and Errors. Every section carries operational value, the core purpose is front-loaded, and there is no filler or redundant prose.

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 2-parameter, read-only lookup tool with an output schema, the description is complete: accepted input forms, output shape, ranking, error behavior, and routing to alternatives are all covered. An agent has everything needed to decide whether and how 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?

Input schema coverage is 100%, so the baseline is 3, but the description adds value with concrete example mappings ('find Apple's CIK' -> {query: 'AAPL'}, 'companies named Berkshire' -> {query: 'Berkshire', limit: 5}), accepted ticker formats like BRK-B/BRK.B, and ranking semantics that affect result interpretation. The Args section duplicates the schema, but the examples and context push it above baseline.

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

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

The description states a specific verb and resource: 'Search SEC EDGAR registrants (US-listed companies) by ticker, company name, or CIK' and identifies the key output (the 10-digit zero-padded CIK). It clearly differentiates from sibling search_dart_company by restricting scope to US-listed SEC registrants, so an agent can distinguish it without inspecting other tools.

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

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

The description has explicit 'Use when' and 'Don't use for' sections that name exact conditions and alternatives: use it to get a CIK or disambiguate a name before get_edgar_* tools, skip it for exact tickers, and use search_dart_company for Korean companies. This is model guidance for when to invoke the tool vs 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?

Beyond the readOnlyHint and openWorldHint annotations, the description reveals ordering behavior ('ordered by popularity'), the exact return shape, the relationship between returned IDs and get_fred_series, and the API-key failure mode. This gives the agent a realistic model of what the tool will do and return.

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 with clear sections: summary, Args, Returns, Examples, and Errors. Every sentence adds useful information, and the most important usage guidance is front-loaded. Despite its length, it remains focused and scannable.

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

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

The description covers what the tool does, how to invoke it, what the response looks like, how to use the response with a sibling tool, and the primary error condition. An agent has everything it needs to decide when to call this tool and what to do with 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?

The input schema already covers both parameters at 100%, so the baseline is 3. The description adds value with richer query examples ('unemployment rate korea', 'housing starts'), explains that results are ordered by popularity, and clarifies how the query maps to real-world series IDs. This goes beyond simple schema repetition.

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

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

The description clearly identifies the tool's verb ('Search'), resource ('FRED catalog for economic time series'), and key qualifier ('by keyword, ordered by popularity'). It also distinguishes itself from get_fred_series by explaining that returned IDs should be passed to get_fred_series, so an agent can tell these siblings apart.

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

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

The description provides explicit when-to-use context: keyword-based discovery when the series ID is unknown. It also gives a direct when-not-to-use rule: if you already know the series ID, call get_fred_series instead. This is exactly the kind of guidance needed to route an agent correctly.

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