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

Annotations already cover read-only/idempotent/no-destruction, yet the description adds substantial behavior beyond them: Yahoo daily split-adjusted closes with dividends excluded (price return, not total return), per-symbol error isolation, a 260-point cap with weekly downsampling on long windows, and the provisional-last-point lifecycle (today's trades vs confirmed close, after-hours never becoming a point). That is exactly the mutation/freshness context annotations cannot express.

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

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

Purpose and the headline workflow are front-loaded, and nearly every sentence carries non-redundant, decision-relevant detail. It is nonetheless a single dense block of several hundred words mixing window rules, sampling, provisional points and output formatting, which makes scanning harder than it needs to be.

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 9-parameter, read-only calculation tool with an output schema, the description covers everything an agent needs: symbol formats and aliases, window selection, benchmark requirements, currency handling, error isolation, and even what the text response contains (one-line summary plus compact JSON mirroring structuredContent). Nothing decision-critical is left to 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?

With 78% schema coverage the schema already names parameters, but the description supplies the semantics the schema lacks: what each of the four metric values means (base-100 normalization, symbol/benchmark ratio, return minus benchmark in %p), which metrics require a benchmark, symbol alias resolution (005930 tries .KS then .KQ), the period vs start/end vs trading_days alternatives, and how currency conversion is performed (Yahoo KRW=X same-date close).

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 (compare), resource (daily price performance) and hard scope (1-8 US/Korean stocks, ETFs or indices on one common trading calendar). It also differentiates itself from generic price-history siblings by explaining that it uses the KOSPI index itself rather than an ETF proxy and aligns cross-market calendars, so an agent can tell it apart without opening the schema.

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

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

Gives an explicit end-to-end usage recipe ('get holdings from investmcp get_holdings, then call this once with their symbols ... and benchmark KOSPI (or SPY/^GSPC)') and states when to prefer it ('cross-market price history and index levels'). It also routes within the tool: if relative strength is requested without a benchmark, it says what happens and what to pass instead.

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

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

Annotations already declare readOnly/destructive/openWorld, and the description adds substantive context beyond them: no account access, no order placement, no FX conversion, warning surfaces (stale spread over 5 minutes, missing options/SEC/consensus data on KRX), and error semantics (ok=false names the problem). The non-idempotent annotation is consistent with a live-quote-dependent comparison.

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

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

Purpose and the alternative-tool routing are front-loaded, and nearly every clause carries operational information with no filler. However, the body is delivered as a few very long run-on sentences packing currency policy, KRX rules, return shape and detail levels together, which makes it harder to scan than it needs to be.

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 6-parameter, multi-market comparison tool this is unusually complete: symbol formats, currency policy, partial-failure behavior, freshness, detail levels and error envelope are all addressed, and an output schema exists so return values need little further explanation. The only omission is horizon_days, which is minor against the overall coverage.

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

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

Schema description coverage is only 17%, so the description carries most of the burden and does so for symbols (format, exchange suffix fallback .KS/.KQ, mixing rules), currency (defaults to listing currency, mismatch behavior, required with total_amount when mixed), total_amount (percentage-only plan for cross-currency tickers), and confirmed_only (confirmed closes). horizon_days is never explained anywhere, and detail is largely covered by the schema itself rather than the description.

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

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

States a specific verb and resource with scope (1–8 tickers, entry-plan scoring and allocation) and immediately disambiguates from siblings by naming compare_price_performance for charts/relative strength. It also clarifies it is a calculation, not an order, so the agent knows what class of operation this is.

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

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

Explicitly routes between tools ('For price-performance charts or relative strength (상대강도), use compare_price_performance') and states what is out of scope (indices, other markets). It also gives the conditions that select behaviors: mixing US and KRX tickers, CURRENCY_MISMATCH when currency conflicts, and unsupported symbols landing in data.unavailable rather than failing the whole call.

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

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

Although annotations already cover safety and openness, the description adds substantial behavior: local-only dataset writes, no orders or uploads, frozen-copy replay with no provider/FX refetch, latest-20 retention, DATASET_EXPIRED on unknown IDs, and privacy handling for account IDs and raw broker payloads. These details materially improve invocation safety and expectations beyond 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 proportionate to an 11-parameter paged export tool with retention and replay behavior. It is front-loaded with the core action and usage constraint, then organized into readable paragraphs and a structured Args section.

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 an output schema present, the description sufficiently covers paging, manifest behavior, row formats, hashing, retention, and error semantics. Given the tool's complexity, schema size, annotations, and output schema, an agent has enough information 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 0%, so the description must carry parameter meaning; the Args section explains all 11 parameters, including defaults, filters, page limits, cursor requirements, and dataset-specific constraints. It adds clear semantics beyond the raw schema, such as page_size being capped by 64 KiB per page and input_snapshot_ids applying only to nav_history.

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 verb and resource: "Freeze an auditable portfolio dataset locally, then return small pages." It also explicitly distinguishes this from the adjacent get_portfolio_returns(include_series=true) use case, which stores nothing.

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 a clear inclusion criterion: "Only for an explicit request to export, save or freeze a dataset." It names the main alternative and when to use it, and it clarifies default date behavior and when to use start_date or period="ALL".

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world. The description adds meaningful caveats beyond that: adjusted prices are 'not verified total returns', the 'before' boundary is 'unverified', and 'complete' covers only the page chain, not historical coverage. That is exactly the kind of epistemic context an agent needs; a pagination/size caveat beyond max 200 would round it out.

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

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

Front-loads purpose, then uses clear Args/Returns structure with no filler. The Returns section is somewhat dense and restates scope ('Raw provider payload for existing calls'), but each sentence adds a real constraint or caveat rather than padding.

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

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

For a 7-parameter, paginated, provider-backed data tool with an output schema, this covers params, paging semantics, return shape, and reliability caveats — enough to call it correctly. The remaining gap is the absence of sibling routing guidance for choosing this versus quote/indicator tools.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does: it explains symbol format examples, interval enum values, count max/default, the meaning of 'adjusted', the nature of 'before' as a provider cursor, and that start/end are inclusive candle-local YYYY-MM-DD labels. Every one of the 7 parameters gains meaning not present in 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 — 'Get candlestick chart data (OHLCV) for a stock (Toss)' — which is unambiguous and clearly different from snapshot/quote tools by naming OHLCV and the provider. It does not explicitly contrast with siblings such as get_quote or get_technical_indicators, so it falls short of a 5.

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

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

Gives procedural guidance for paging ('One page per call', 'Merge pages ascending by timestamp and deduplicate'), which implies when the tool is appropriate. However, it never says when to prefer this over get_quote, get_technical_indicators, or compare_price_performance, and offers no guidance on choosing interval or date ranges.

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

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

Annotations already cover read-only/idempotent safety, and the description goes further: newest-first ordering, cursor paging, limit range 1-500 default 50, per-venue coverage in the page header, and values kept in native asset. It also discloses that fetched rows land in a local append-only ledger with no broker writes — a meaningful side effect the annotations don't express. Rate limits and auth needs are unstated, keeping it at 4.

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

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

Front-loaded with the core result, then parameter detail in a compact block; no filler sentences. The parenthetical about the local ledger is appended slightly awkwardly but 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?

With an output schema present the description needn't explain return values, and annotations cover the safety profile, so the remaining burden is paging and filtering semantics — paging is fully handled and date filtering is precise. Only the symbol/venue filter semantics leave a real gap for a 7-parameter tool.

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

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

Schema description coverage is 0%, so the description must carry the load; it does for start/end (inclusive UTC YYYY-MM-DD, default last 7 days), limit (1-500, default 50) and cursor (next_cursor), plus `kind` via the opening sentence. But `symbol` and `venue` are never explained — venue is only obliquely hinted at via 'per-venue coverage'. Partial compensation.

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 names the exact resource (own crypto futures fills with fees, or funding paid/received) and its ordering/paging behavior, which is clearly distinct from siblings like get_crypto_positions or get_trading_pnl. It never names a sibling to contrast against, so it falls short of a 5.

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

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

Usage is implied through the `kind` enum (fills vs funding) and the default 7-day window, but the description never states when to reach for this tool over get_trading_pnl or get_transactions, nor any prerequisite (e.g. broker connection must exist). Guidance is present but inferential.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-redundant behavior: it is public and keyless, always returns a fixed snapshot set, and clarifies that each include returns limit rows (1-500).

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

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

Front-loaded with scope and auth first, then the return contract, then the optional expansions. Every clause carries information; minor density in the include/interval/limit sentence, but nothing 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?

An output schema exists, so return values needn't be fully spelled out, yet the description still names the snapshot contents. Combined with the include semantics and limit range, an agent has enough to call it correctly; only the default limit and interaction with the base snapshot are unstated.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: it names the three valid include values, ties interval to candles, and constrains limit to 1-500 rows per include. The symbol format is given by example. It omits the limit default (30) and whether limit applies to the snapshot too, so not a full 5.

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

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

States a specific verb and resource: public Binance USD-M futures market data for one symbol, naming the exact snapshot fields returned. It does not explicitly differentiate from the overlapping sibling get_candles, which it partially duplicates via the 'candles' include option.

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?

'No API key' establishes a key prerequisite for public data access, and 'Always returns the snapshot' tells the agent what happens by default. However, it never says when to prefer this tool over get_candles or get_quote, leaving the choice between overlapping siblings to inference.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the bar is lower, and the description still adds genuine value: it discloses that leverage, margin mode and mark prices are returned as null when unknown and points the agent at per-venue source_status and coverage fields for data quality. That is exactly the kind of caveat an agent needs before interpreting results.

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

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

Two compact sentences with the subject front-loaded and no filler. The second sentence is a slightly telegraphic fragment ('Kept out of portfolio NAV and holdings'), but it carries real routing information rather than padding.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety profile. The description fills the remaining gaps — venue scope, exclusion from portfolio aggregates, and null-handling for missing fields — leaving little an agent needs that isn't covered.

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

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

Only one parameter exists and schema description coverage is 0%, but the enum (all/binance/hyperliquid) is self-documenting. The description names both venues, which maps onto the enum values, yet it never mentions the parameter itself, the 'all' default, or what 'all' returns.

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

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

Names a specific resource — open crypto futures positions plus native account balances — and scopes it to two named venues (Binance USD-M, Hyperliquid). The sentence 'Kept out of portfolio NAV and holdings' actively separates it from siblings like snapshot_portfolio_nav and get_holdings, so an agent can route correctly without opening the schema.

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

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

The exclusion note ('Kept out of portfolio NAV and holdings') implies that portfolio-level questions belong to sibling tools, which is useful implied guidance. However, it never states explicitly when to call this tool versus get_crypto_account_history or get_trading_pnl, and names no alternative by name.

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 read-only/idempotent/open-world; the description adds substantial context the annotations cannot: it is a calculation, not a forecast or price target; pre-split fiscal years are dropped rather than adjusted; the P/E band is applied only when EPS bases match, otherwise nulls plus a needs_input_pe_multiples note; confirmed_only switches between latest trade and completed close. It is dense but genuinely informative, though the source caveat for yfinance (unofficial) is the only reliability marker.

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 routing instruction is front-loaded correctly, but the remainder is a series of long run-on sentences mixing output format, edge cases, provenance fields and timing semantics. Little is truly wasted, yet the density makes it hard to scan and the JSON-return description could be tightened.

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

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

Covers the full call path for a complex derived-metrics tool: sources, edge cases (splits, unsupported markets), the human-in-the-loop pe_multiples recovery path, reference price timing, and text/structuredContent parity. Even though an output schema exists, the description still tells the agent how to present the result and which fields to surface.

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 by giving a concrete pe_multiples example ({"bear":25,"base":32,"bull":40}) and explaining what confirmed_only switches between (latest trade with session/basis vs last confirmed close). Those are behavioral consequences of the parameters rather than restatements of the schema text.

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

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

States a specific computation: GAAP diluted EPS per fiscal year from SEC EDGAR 10-K filings, Yahoo consensus EPS, and bear/base/bull implied prices from EPS x P/E. It is clearly distinguished from siblings like get_sec_financials and get_key_metrics by naming the derived scenario output rather than raw financials.

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 to call this first for any EPS question on a US SEC filer, before web search, and that news can be layered afterwards. It also names what is out of scope (Korean listings/indices return UNSUPPORTED_MARKET, no dividends), which gives routing rules in both directions.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior, and the description adds the external yfinance source plus a structured JSON return envelope. It does not cover data latency, rate limits, or failure modes, but that is a limited gap given annotation coverage.

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 and has clear Args/Returns sections, but the market/ticker examples are repeated in the body and again under Args, and yfinance is mentioned twice. It is readable but not maximally economical.

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 and safety annotations already present, the description covers the source, data types, and parameter format. It is still incomplete for tool selection because it does not distinguish this comprehensive yfinance financials tool from nearby financial siblings such as get_sec_financials, get_ttm_financials, or get_key_metrics.

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

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

The single parameter has zero schema description coverage, but the description fully compensates with 'Stock ticker' and concrete US/Korean/Japanese ticker examples. For a one-parameter tool, that is enough to invoke it 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 uses a specific verb ('Get') and resource ('comprehensive financial data from yfinance') and enumerates the statement/metric types, so the agent knows exactly what it returns. It does not explicitly name the sibling tools it replaces (e.g., get_sec_financials, get_ttm_financials), so it stops short of full sibling differentiation.

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

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

It states the coverage markets (US, Korea, Japan) and gives ticker examples, which implies when the tool is applicable. However, it never states when not to use it or which sibling to choose for SEC/TTM/key-metrics needs, leaving alternatives to inference.

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

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

Annotations already cover the read/write safety profile, and the description adds real value beyond them: it discloses merge behavior (native + KRW), that 'raw' returns unmerged broker payloads, and that rows are appended to a local ledger with no broker writes. It stops short of noting rate limits or freshness/latency.

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

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

The core output is front-loaded in the first sentence, with parameter nuances following in compact clauses. Dense and largely waste-free, though the multi-line enumeration is slightly heavier than necessary.

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

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

An output schema exists so return shape need not be spelled out, and the description covers the key behavioral facts an agent needs: merge basis, the three fidelity levels, and the ledger side effect. Adequate for a 3-param read tool.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for two of three params: it enumerates the account values (including the 'toss:primary' label format) and fully explains the three detail_level modes. include_cash is only gestured at ('plus cash') and its toggling is not explained.

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

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

States a specific resource (current positions/cash) and its merge semantics (merged per symbol in native currency and KRW). This clearly separates it from get_crypto_positions and get_transactions, though it never names a sibling explicitly to draw the boundary against get_portfolio_summary.

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

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

Usage is only implied through the account and detail_level value descriptions; there is no explicit 'use this instead of X when Y'. An agent can infer which detail level fits, but the choice between this and get_portfolio_summary / get_crypto_positions is left unstated.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new context: the upstream source (SEC Form 4), US-only coverage, the P/S transaction codes, and that non-trade events like grants and tax withholdings are included. It stops short of noting data lag (Form 4 filing delay) or any rate/limit 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?

Front-loaded with the core purpose, then a scannable Args/Returns block; every line is short and useful. The coverage enumeration ('plus option exercises, grants, tax withholdings, etc.') is slightly padded but conveys legitimate scope 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?

An output schema exists, so the description needn't detail return values, and its one-line return note suffices. Annotations cover the safety profile. The remaining gap is the undocumented detail_level parameter, which is material for a three-parameter tool with zero schema-description coverage.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It documents symbol as a US ticker and adds a real constraint the schema lacks (days_back default 180, max 365), but it omits detail_level entirely despite that being a summary/full enum that changes the response shape.

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 ('Get insider trading data from SEC Form 4 filings') plus a scope qualifier ('US stocks only'), which separates it from portfolio-oriented siblings like get_transactions and get_holdings. It never names a sibling explicitly, so differentiation is inferential rather than stated.

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 'US stocks only' qualifier and the Form 4 sourcing imply when this tool applies, and the enumerated trade categories help the agent recognize relevant data. However, there is no explicit when-to-use/when-not guidance and no routing against alternatives such as get_transactions or get_ticker_research.

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 that this is a read-only, idempotent, non-destructive, open-world operation. The description adds useful behavioral context by naming yfinance as the source and identifying the metric categories returned. It does not discuss rate limits, data freshness, or source limitations, so it stops short of full transparency.

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 short and front-loaded, with a clear purpose sentence followed by metrics, args, and returns. The Returns sentence is somewhat redundant because an output schema exists, but overall there is little waste.

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

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

For a one-parameter read-only financial data tool with annotations and an output schema, the description covers source, metric scope, supported markets, and symbol format. It is sufficient to invoke the tool correctly, though it omits sibling routing and data freshness caveats.

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

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

Schema description coverage is 0%, so the description must carry parameter semantics, and it does. It explains that symbol is a stock ticker and gives concrete formats for US, Korean, and Japanese tickers.

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: getting a key financial metrics summary. It also lists representative metrics and supported markets, making the tool understandable. However, it does not explicitly differentiate itself from close siblings such as get_financials, get_ttm_financials, or get_stock_snapshot.

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

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

The listed metrics imply valuation and profitability use cases, and the market examples imply coverage scope. But there is no explicit guidance on when to choose this tool over alternatives like get_financials or get_stock_snapshot. Usage is inferable rather than stated.

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

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

Annotations already state read-only, idempotent, open-world, non-destructive behavior. The description adds useful provenance/freshness context by naming providers and saying each section's meta contains provider and as_of, but it omits rate limits, availability caveats, or failure 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?

One dense sentence covers the three data sections and the meta note with little waste. It is front-loaded, though the compressed semicolon list could be structured more readably.

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

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

An output schema and rich annotations reduce what the description must cover, and it identifies the data sections and providers. However, with 0% input-schema descriptions, it leaves the agent unable to confidently use base/quote/include beyond defaults.

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

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

Schema description coverage is 0%, so the description must explain the four parameters, but it never mentions base, quote, include, or their defaults. It only indirectly signals market values KR/US and the three data sections, leaving base/quote semantics and include filtering undocumented.

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

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

Names three concrete data sections and their providers, so the resource is identifiable. It does not use a verb or explicitly contrast with siblings, though no sibling covers the same market-calendar/FX/risk-free data.

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

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

There is no when-to-use or when-not-to-use guidance, no alternatives, and no prerequisites. The section list only implies the tool's domain; an agent must infer that it should be called for market hours, FX, and risk-free rate data.

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

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

With readOnly/idempotent annotations already covering the safety profile, the description still adds non-obvious behavior: nothing is persisted for the series view, no export or snapshot step is required, and no broker-side writes occur. Minor tension: it says fetched rows are recorded in a local append-only ledger, which is a state change, though the description is explicit that broker-side writes do not happen.

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

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

Front-loaded with the primary output, then the optional series behavior, then the side-effect caveat. Sentences are dense but each carries information; the ledger sentence is slightly tangential but earns its place by preempting a write concern.

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

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

An output schema exists, so return values needn't be described, and the safety story is covered. What's missing is the meaning of scope and detail_level, which materially change what comes back from an otherwise adequately described tool.

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

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

Schema coverage is 0% and three of four parameters are enums with no explanation. Only include_series gets any treatment; scope (equity vs consolidated vs toss vs kis) and detail_level are left entirely unexplained, which is a substantial gap since scope in particular selects fundamentally different data.

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 names the resource and enumerates the concrete outputs (simple return, TWR, XIRR, P&L split, NAV risk statistics), so the purpose is unambiguous. It does not, however, differentiate itself from close siblings such as get_portfolio_summary or get_trading_pnl, which an agent must choose between.

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

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

It states the data source (stored daily NAV snapshots plus ledger) and gives a clear condition for include_series, which is genuinely helpful. But it never says when to prefer this over get_portfolio_summary, snapshot_portfolio_nav, or get_trading_pnl, leaving sibling routing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: broker rows are fetched live into a local append-only ledger with no broker writes, values are in KRW at current spot, leveraged products use the daily multiple, and open crypto futures are carried at signed notional but excluded from totals. The '(slower)' note on realized P&L is a useful performance caveat as well.

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 first clause front-loads the scope, then each section gets one tight clause with no filler; the closing two sentences carry the no-write guarantee. Density is high but every sentence contributes distinct information for section selection or trust calibration.

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

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

With an output schema present the return shapes need not be restated, yet the per-section inventory adds selection value without becoming a schema dump. Safety (annotations + explicit no-write statements), currency, valuation conventions, and the slower-path caveat are all covered; only detail_level semantics are missing, which is minor relative to the whole.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it does so thoroughly for 'sections' — each enum value is defined with its contents (NAV bridge, HHI, look-through exposure, ledger-sourced realized P&L). 'detail_level' ('summary' vs 'full') is never mentioned anywhere, which is a real gap given zero schema coverage.

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

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

The opening line states a specific resource and scope: whole-portfolio totals across every broker account, decomposed by section. The four section names are enumerated with what each returns, so an agent knows exactly what capability this represents and can distinguish it from sibling holding/return 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 supplies the default section pair (totals + realized) and marks 'realized' as '(slower)', which is actionable cost guidance for choosing sections. It also clarifies the tool never writes a snapshot, implicitly steering write-intent callers to snapshot_portfolio_nav. However, no sibling is named explicitly and there is no stated when-not-to-use condition.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior, so the bar is lower. The description adds meaningful operational context: provider fallback logic, Toss-key dependency, session-timing comparison for 'both', per-symbol include behavior, and KIS Japanese-stock support.

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

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

The description is front-loaded with the core purpose and then moves into provider/include details with little wasted text. It is dense but appropriate for a six-parameter tool, though the long semicolon-and-parenthetical sentence could be easier to scan.

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

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

There is an output schema, so return values need not be explained. But with 6 parameters, only 1 required, and 0% schema description coverage, the description omits meanings for market and detail_level and only partially explains exchange, leaving clear gaps for an agent configuring the call.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains symbols (up to 10, with examples), provider modes, include values, and partially exchange via 'KIS covers Japanese stocks (exchange TKSE)'; however, it does not explain market or detail_level and only partially covers exchange.

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: 'Current stock quotes for up to 10 symbols' with example symbols. It is clear what the tool returns, but it does not contrast itself with related siblings such as get_stock_snapshot or get_candles, so an agent may still need to infer the boundary.

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

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

Usage is implied by the first sentence and by the provider-selection details, but the description never explicitly says when to use this tool instead of alternatives like get_stock_snapshot or get_candles. The provider guidance helps configure the call, not choose the tool.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description goes beyond them by disclosing data provenance, the fair-access requirement via SEC_USER_AGENT, absence of an API key requirement, and how missing data is surfaced ('marked unavailable or carries warnings'). That is meaningful operational context an agent cannot get from the annotations, though it does not quantify rate limits or latency.

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

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

The most decision-relevant content (what is returned and the coverage caveat) is front-loaded in the first two sentences, with provenance and Args/Returns following in a predictable structure. The Returns section partly restates the output schema, which is mild redundancy, but nothing is padded or circular.

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 read tool with a published output schema, the definition supplies nearly everything needed: sources, edge-case handling, auth/environment requirements, and a return summary. The one genuine gap is routing guidance against the heavily overlapping financials siblings, which the description leaves entirely implicit.

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

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

Schema description coverage is 0% and the single property has no description, so the description must carry the load — and it does, defining 'symbol' as a US stock ticker with concrete examples ('AAPL', 'MSFT'). The US-only constraint is real added meaning beyond the bare string type, though it stops short of specifying case, suffix, or exchange-qualified formats.

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

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

The description names a specific verb and resource ('Get SEC financials') and enumerates the exact data classes returned: up to five annual fiscal years, quarterly facts, derived TTM, earnings quality, and segment revenue. It is clearly not a portfolio or price tool, but it never distinguishes itself from close siblings like get_financials, get_ttm_financials, or get_key_metrics, which overlap heavily in scope.

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 conveys useful invocation context: coverage caveats ('quarters/TTM/segments are not guaranteed'), the underlying sources (CompanyFacts, 10-K/10-Q, amended forms), and that no API key is required. However, in a sibling set containing get_financials, get_ttm_financials, and get_key_metrics, it gives no explicit rule for when to choose this tool over those 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 readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: passive mode makes no upstream calls, probe hits every market-data source once (implying latency), and accounts performs live per-account checks. The outstanding gap is any note on failure handling or how long a probe takes.

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?

A one-line purpose followed by per-mode definitions, front-loaded and free of filler. The help-topic list is somewhat dense inline but every clause maps to an enum value an agent must choose between.

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

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

An output schema exists, so return-value shape need not be described, and mode/topic semantics are fully covered. The only omission is what detail_level changes, which matters since a caller can select it.

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

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

Schema coverage is 0%, so the description carries the full burden and mostly does: all four mode values are explained and the help-topic vocabulary is enumerated in full. The third parameter, detail_level (summary/full), is not mentioned anywhere, leaving one enum undocumented in both schema and description.

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

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

The description opens with a specific verb+resource framing ('Connector status') and enumerates the four distinct payloads the tool can return (cached health, live probes, accounts, usage guide). It is clear this is a diagnostics tool, implicitly distinct from the data-fetching siblings, though it never names a sibling to draw that boundary explicitly.

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

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

Each mode is given a use-defining behavior: passive = cached only, no upstream calls; probe = one call per source; accounts = lists and live-checks each broker account; help = usage guide. This effectively tells an agent which mode to pick and what the cost tradeoff is. It does not state when to call this tool at all versus the sibling tools, which keeps it from a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds that analyst consensus is provider-sourced and that insider data is folded in, but it says nothing about latency, rate limits, partial-data behavior, or market coverage (the us/kr enum goes unmentioned).

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?

A single front-loaded sentence that lists the payload contents without a word of filler. Nothing could be cut without losing 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?

An output schema exists, so return values need no explanation here. However, for a two-param tool with an undocumentable 'auto' market default and no routing guidance against 26 siblings, the description leaves real gaps an agent would need to guess at.

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

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

Schema description coverage is 0% – neither symbol nor market is documented anywhere. The description offers no compensating detail, notably nothing about what "auto" means for market detection or whether symbol format differs between us and kr. Only the word "stock" implies symbol is a ticker, distinguishing it from the crypto siblings.

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

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

States a concrete verb ("Return") and resource ("compact stock snapshot") and enumerates the bundled content: quotes, financial metrics, analyst consensus, insider data. That enumeration implicitly distinguishes it from the narrow siblings get_quote, get_key_metrics, and get_insider_trades, but it never says so explicitly.

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

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

There is no when-to-use guidance and no named alternative. An agent cannot tell from this text whether to call get_stock_snapshot or to compose get_quote + get_key_metrics + get_insider_trades; only the adjective "compact" hints at a bundled overview.

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 read-only and idempotent, but the description adds critical behavior: data source (Yahoo daily closes, price return), provisional last bar handling with session details, confirmed_only effects, warm-up bar requirements, possible split discontinuities, and numerical differences in recursive indicators.

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

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

Despite its length, the description is front-loaded with purpose and every sentence adds necessary detail about parameters, behavior, or edge cases. No wasted information; the density is justified by the tool's complexity.

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

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

An output schema exists, but the description still provides enough context about returned series, tables, and warnings to set expectations. Combined with annotations and schema, it is fully complete 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 coverage is 100%, but the description adds substantial practical constraints not in the schema: max 6 indicators, length limits 2-400 with recursive limit 252, warm-up need of 10x n, how to request multiple SMAs, max 260 daily points, and the meaning of confirmed_only.

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: daily technical indicators for a single stock, ETF, or index. Distinguishes from siblings by naming get_holdings for symbol lookup and warning against computing from raw candles, and notes consistency with plan_entry and compare_tickers.

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

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

Explicitly says when to use this tool instead of computing indicators manually and how to get symbols for holdings. Also explains the tradeoff of confirmed_only and the consistency guarantee with sibling tools, leaving no ambiguity.

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

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

Annotations already cover read-only/no-destroy safety, and the description adds genuinely new behavioral context: data comes from SEC EDGAR and unofficial yfinance, refresh is explicit, and ok=false is surfaced as a tool error naming the problem. It stops short of disclosing rate limits, caching/staleness windows for refresh, or the cost of 'full' detail, which keeps it below 5.

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

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

The first sentence is well front-loaded and information-dense, but the remainder is a long run-on block that duplicates the detail-level rules already present in the schema and buries the freshness rule mid-paragraph. No outright waste, but structure and layering could be sharper.

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

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

An output schema exists and the description still helpfully maps the top-level envelope and section names (sec_financials, yfinance_metrics, factors, freshness), which is appropriate for a multi-source aggregation tool. The gaps are the undocumented 'confirmed_only' and 'refresh' semantics rather than return-value description.

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

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

Schema description coverage is only 25%, so the description should compensate, yet it elaborates mainly on 'detail' levels that the schema already documents in comparable detail, and mentions 'refresh' only in passing ('explicit refresh'). 'confirmed_only' is never explained anywhere, and 'symbol' is left implicit.

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

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

States a concrete resource ('Issuer facts and explainable factors for one US ticker') and scope boundaries ('no account access or orders'), which helps separate it from portfolio/order siblings. It does not, however, distinguish itself from overlapping siblings like get_stock_snapshot, get_sec_financials or get_technical_indicators, which appear to return portions of the same data.

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

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

There is one useful usage rule: 'For prices now/today/intraday use freshness, not the factors' bar dates', which governs interpreting output. But there is no guidance on when to choose this tool over the many sibling tools that expose quotes, candles, SEC financials or indicators, and no routing to get_ticker_research_status.

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

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

Goes beyond the annotations by disclosing that no provider calls occur, the exact envelope {ok, data, error, meta}, that it is returned as both structuredContent and compact JSON text, and that ok=false signals a tool-level error naming the problem. The listed data fields (provider readiness, auth mode, planning_configured, latest-price source health) tell an agent what failures mean. Minor inconsistency: annotations claim idempotentHint=false for a passively-read status snapshot, but the description does not contradict them outright.

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

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

Front-loaded with the key fact (passive, no provider calls), then the return contract. Dense semicolon packing is efficient though it reads like a spec dump; every clause does carry 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?

Covers behavior, error semantics, and the meaning of the returned data fields, which is more than enough for a zero-argument status tool that also has an output schema. The only gap is guidance on when in a workflow to call it and how it relates to get_status.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies.

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

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

States a specific verb+resource: a passive configuration/status read for ticker research, and explicitly notes it makes no provider calls. It is clear what the tool does, but it never distinguishes itself from the look-alike sibling get_status or explains its relationship to get_ticker_research.

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

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

Usage is only implied: 'Passive configuration status; performs no provider calls' suggests a cheap pre-flight diagnostic before invoking the paid research path, but the description never says when to call it or names an alternative. With siblings like get_status and get_ticker_research present, an explicit routing sentence is missing.

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

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

Annotations already cover read-only, idempotent, non-destructive and open-world, so the marginal bar is met by the description adding real side-effect context: fetched broker rows land in a local append-only ledger with no broker writes. It also discloses result-truncation behavior (20 rows / top 10 by |realized P&L|, omitted_symbols). It does not mention cost of fetching or rate/limit 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?

It is front-loaded with the core definition and each subsequent clause conveys distinct information with almost no filler. Some clauses are dense and reference undeclared fields ('symbols_page has the total', 'reason groups (symbol_count, omitted_symbols)'), making it harder to scan than it needs to be.

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, zero-required tool with annotations and an output schema, the description covers mode selection, date precedence, truncation and write side effects. The remaining gap is per-parameter meaning for 'account' and 'period', which an agent must infer from the enum and default.

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

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

Schema description coverage is 0%, so the description carries the burden and mostly does: view enum values, ISO format and override precedence for start/end, detail_level summary-vs-full, and symbol for drilling in. The 'account' parameter and the period enum values (MTD/YTD/ALL) are never explained beyond the default, leaving partial gaps.

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

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

The first line states a specific resource and metric (realized trading P&L) plus the accounting method (per-account moving-average cost basis), which is more precise than the name alone. The two 'view' bullets further split the tool into its two modes. It does not name or contrast with siblings such as get_portfolio_returns or get_transactions, so it stops short of a 5.

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

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

It tells the agent which view to pick and what each returns, states that start/end override period, and explains that 'summary' truncates while passing symbol or detail_level 'full' expands to every symbol. That is actionable routing within the tool. It offers no exclusions or comparison against alternative portfolio/P&L tools, so no 5.

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

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

Annotations already cover the read-only/idempotent profile, yet the description adds genuinely non-obvious behavior: fetched broker rows are written to a local append-only ledger, 'no broker writes'. It also discloses pagination via next_cursor, that the page header carries window-wide totals/counts, and that 'raw' returns one source at a time.

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

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

Front-loaded with the what and ordering, then parameter semantics packed densely with zero filler. The detail_level sentence is a run-on that mixes three modes plus the one-source-at-a-time constraint, but 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?

An output schema exists, so return values needn't be explained, yet the description still usefully sketches the page header's totals and cursor. With 7 parameters and 0% schema coverage, the only real omission is the unexplained 'symbol' filter.

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

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

Schema coverage is 0%, so the description must carry the load, and it does: ISO date format with a 90-day default, account values ('all', 'toss', 'kis' or a label), limit bounds 1-500 with default 100, cursor as next_cursor, and full semantics for the three detail_level modes. Only the 'symbol' parameter is never mentioned, leaving one of seven undocumented.

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

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

States a specific resource and scope: 'Your trades across every Toss and KIS account, newest first, one page at a time.' This clearly separates it from holdings/snapshot siblings by making it a historical transaction feed. It does not explicitly name a sibling it is not, which keeps it just shy of a 5.

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

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

Usage is implied rather than stated: the agent can infer this is the trade-history listing versus get_holdings or get_trading_pnl, but the description never says when to prefer this tool or when to use an alternative. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful provenance (TTM computed from 10-Q/FY filings) and a scope limit (US stocks only), but says nothing about freshness, missing-data behavior for non-US or non-filing companies, or latency.

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?

A single, densely packed sentence with the distinguishing qualifier 'TTM' and the source in the front half. Nothing is wasted and nothing needs reordering.

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

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

With an output schema present, return shape needn't be explained, and the read-only annotation covers safety. Still, for a tool sitting in a cluster of five overlapping financials tools, the description omits the selection rule and any note about filing-based lag or coverage gaps, which are exactly the facts an agent needs to call it correctly.

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

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

Schema coverage is 0% and the single parameter 'symbol' has no description, so the schema contributes nothing. The description partially compensates by implying the value is a US-listed ticker, but gives no format example or resolution rules (e.g., class shares), so meaning is only loosely filled in.

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

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

The description names a specific verb+resource ('Get ... TTM financials') and adds qualifying detail about the data source ('SEC 10-Q/FY-derived') and scope ('US stock'), which distinguishes it from a generic financials tool. It does not, however, explicitly contrast itself with close siblings like get_sec_financials or get_financials, leaving the agent to infer that 'TTM' is the differentiator.

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

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

There is no guidance on when to prefer this over get_financials, get_sec_financials, or get_key_metrics, nor any stated exclusions or prerequisites. The agent must guess which financials tool fits a given question.

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, the description adds critical behavior: step 1 writes nothing, step 2 stores planned rows locally, blocked plans cannot be confirmed, no orders are placed, and previews expire after 15 minutes. These details materially clarify the mutation model and safety constraints.

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

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

The purpose is front-loaded, followed by a tightly structured two-step procedure and key constraints. Every sentence adds operational value with no redundant 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 two-step import tool, the description covers the important workflow, write behavior, blocking conditions, and preview expiry, while an output schema exists to describe returns. The remaining gap is the undocumented account parameter, but the overall definition is nearly complete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains file, preview_id, and confirm well, including the two-step interaction, but it does not explain the account parameter or its auto default.

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: importing Toss stock BUY/SELL rows from a private-inbox PDF statement into the local ledger. It clearly distinguishes this import path from sibling read/query tools and states that it never places orders.

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

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

It gives explicit two-step usage: first call with file to preview, then call with preview_id and confirm=true to store rows. It also states blocked plans cannot be confirmed, but it does not name any alternative tool or broader when-not-to-use 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?

Goes well past the annotations: it discloses the data source and resolution (Yahoo daily bars, latest trade only for KRX), explicit exclusions surfaced as warnings (no options levels, SEC filings, consensus, earnings date), the KRX tick-grid rounding rule and whole-share constraint, and the error contract (ok=false is a tool error naming the problem). It also clarifies staleness semantics — spot is the latest trade from any session and indicators include today's provisional bar unless confirmed_only=true — which is exactly the behavioral context annotations cannot express.

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 critical constraints (not an order, no account access, symbol formats, currency mismatch) are front-loaded and the rest is grouped by concern — sources, return shape, detail levels. It is dense and the detail-level paragraph substantially restates the schema's own enum description, which is the main wasted space.

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 analytical tool with an output schema, this covers everything an agent needs to call it correctly: accepted symbol markets, currency coupling, error signaling, and how detail levels change payload shape (meta.detail_note, dropped_levels formats, style_parameters only in full). No material unknown is left for a 7-parameter, market-scoped calculation.

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

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

Schema coverage is only 14%, so the description carries most of the load, and it does: symbol syntax (US tickers, KRX codes with .KS then .KQ fallback, explicit 000660/005930 examples), currency defaulting and the USD-on-KRX / KRW-on-US CURRENCY_MISMATCH failure, amount as the required input, and confirmed_only's effect on bars and spot. Gaps remain: style and horizon_days get no explanation at all beyond a passing mention that style constants exist.

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

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

The opening clause names a specific computation ('Scaled entry calculation') and immediately disqualifies the most likely misreading ('not an order; no account access'), which separates it from execution-style tools in the sibling list. It also names the concrete artifact produced (tranches with price, percent, amount, touch probability). It stops short of naming an actual sibling to route away from, so it lands at a clear-but-not-exemplary 4.

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

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

Usage is only implied: the reader must infer 'call this when you want a tranche plan rather than an order or a raw indicator dump.' The negatives ('not an order', 'no account access') are framing, not when-to-use guidance. The one real routing hint is that RSI/MACD/ATR/MAs come from the same bars as get_technical_indicators, but it never says to prefer that tool for indicators alone.

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

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

Goes well beyond the annotations: explains that re-running appends an immutable version and moves that date's representative, the exception when a scheduled capture with crypto evidence holds it, and that only derived valuations hit local SQLite with no broker state touched. This also explains why idempotentHint is false.

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

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

Front-loaded with the action and the gating condition, then behavior, then args. Dense but nearly every clause earns its place; the 'see deploy/ for a systemd timer' pointer is mildly incidental for an agent invoking the tool.

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

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

With an output schema present, return values need no elaboration beyond the brief mention of a structured JSON envelope. The mutation semantics, scheduling interaction, and refusal rule are all covered.

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

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

Schema coverage is 0%, so the description carries full burden for the single parameter — naming its ISO YYYY-MM-DD format, today default, and the reason other dates are refused (collection uses current prices). That framing is unavailable anywhere in 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 ('Store today's portfolio NAV snapshot for history and TWR') plus the storage target ('local write'). An agent can immediately distinguish it from read-side siblings like get_portfolio_returns and get_portfolio_summary.

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

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

Explicitly names the trigger ('Only on an explicit request to store a snapshot now'), the automated alternative (scheduled 18:10 KST job), and the exclusion ('reading returns or history needs no snapshot'). No inference required.

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