Portfolio Terminal

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

Annotations already establish read-only, idempotent, non-destructive behavior, while the description adds useful scope details: the covered universe, the bundled outputs, risk rating, support/resistance, holders, and related research. It does not discuss data freshness beyond "dated" or behavior for unsupported tickers.

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 resource and output bundle, and the use-case examples are useful. It is dense and long, but most enumerated items earn their place by clarifying the returned content.

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

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

Given the rich annotations, 100% schema coverage, and an output schema, the description provides enough detail about scope, returned facts, coverage universe, and intended queries. Nothing essential for correct invocation appears to be missing.

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

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

Schema description coverage is 100% and the single ticker parameter is well documented in the schema. The description reinforces that the ticker must be covered by Portfolio Terminal, but adds no syntax or format details beyond the schema.

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

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

The description states a clear single-ticker resource and enumerates the key facts and chart read it returns. It implicitly separates itself from multi-ticker or specialized sibling tools by saying "one ticker," but it does not explicitly name alternatives such as compare or who_holds.

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 example queries ("how is NVDA doing", "is TSLA near its high", "what does the AAPL chart say") that clearly indicate when to use it. It lacks explicit when-not guidance or direct routing to sibling tools for narrower tasks.

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

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

Annotations already cover read-only, idempotent, non-destructive, open-world, so the description is free to add real behavioral context: the five-year window, weekly closes, dividend/split adjustment, and the full returned metric set including fee for funds. The "covered" qualifier also warns about instrument coverage limits, which is not in any structured field.

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 window, then the metric list, then usage examples — a sensible order. The metric enumeration is long and partly duplicates the output schema, so a sentence could be trimmed, but nothing is genuinely wasted.

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

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

With an output schema, fully described params, and rich annotations, the remaining burden is methodology and scope, both of which are covered (weekly closes, dividend/split adjustment, five-year horizon, coverage restriction). An agent can call this correctly without opening anything else.

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

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

Schema coverage is 100% for both tickers, so the schema carries the syntax and examples. The description adds the meaningful constraint that inputs must be covered stocks or ETFs and shows a matched pair per asset class, which is more than restating 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+resource+scope: a five-year head-to-head of exactly two tickers, with the exact metric set enumerated. It is clearly distinct from single-ticker siblings like analyze_ticker or fund_fees because the two-input comparison is stated up front.

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 closing line gives concrete triggering phrasings ("SCHD vs VIG", "NVDA vs AMD") and the description scopes inputs to "covered" stocks or ETFs. It stops short of naming alternatives or stating when not to use it (e.g., one ticker → analyze_ticker, overlapping ETFs → etf_overlap).

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so safety is covered. The description still adds real context the annotations cannot: the covered universe (420 tickers), and critically that each date is either 'confirmed by the company or estimated from its payment rhythm' — a data-reliability caveat an agent must know before presenting dates as fact.

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

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

Front-loaded with the resource and its output, then the caveat, then the filter hint — good ordering and no filler paragraphs. Minor noise: the awkward fragment 'of the 420 Portfolio Terminal covers' and the advisory 'Buy before the ex-date' sentence, which is orientation rather than tool description.

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, and all five parameters are fully documented in the schema. The description supplies the remaining essentials: universe scope, date-estimation caveat, and the single-ticker filter path. Nothing an agent needs in order 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 description coverage is 100%, including the mutual exclusivity of `month` and `from` and the range bounds, so the baseline of 3 applies. The description restates only that `symbol` filters to one ticker, adding no syntax, format, or behavioral nuance beyond the schema.

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

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

The first sentence names a specific verb+resource ('going ex-dividend'), the asset universe (US stocks and ETFs), the time dimension (a month or a date range) and the projected fields (ex-date, pay date, DPS, yield, frequency, confirmed vs estimated). That is far more specific than the name alone. It does not explicitly contrast itself with the adjacent `earnings_calendar` sibling, though the dividend framing makes confusion unlikely.

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: 'Filter by one ticker with `symbol`' hints at the narrowing path, and 'Buy before the ex-date to receive the dividend' is a domain tip rather than invocation guidance. Nothing states when to choose a month vs. a from/days range, or when to reach for this over `earnings_calendar` or `analyze_ticker`.

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 real value by declaring the coverage universe (only 390 US companies) and by explaining that dates may be 'confirmed or estimated' and results appear only 'once out' — semantics an agent could not infer from 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 payload is front-loaded into one dense sentence that leads with the resource and scope before listing fields, and the final sentence gives the one actionable filter. It is somewhat clause-heavy but every clause carries information; no filler sentences.

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 parameter documentation is complete, so the description need not explain return values, and it correctly focuses on what the data represents (estimates vs. actuals, confirmed vs. estimated). Minor residual gaps — pagination behavior via `limit` and the 'larger companies first' ordering — are covered by the schema rather than the description.

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

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

Schema description coverage is 100%, so the schema already documents ranges, defaults, and mutual exclusivity of `month` vs `from`. The description only restates that `symbol` filters to one ticker and that a month or a date range is accepted, adding essentially no syntax or format detail beyond structured fields; baseline 3 applies.

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

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

The description names a specific resource and verb ('companies reporting earnings') and enumerates exactly what the tool surfaces: the day, BMO/AMC timing, EPS and revenue estimates, confirmed vs. estimated status, actual vs. consensus, and beat streak. It also states the covered universe (the 390 Portfolio Terminal companies), which lets an agent distinguish it from dividend_calendar and analyze_ticker without opening a schema.

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

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

It explains that `symbol` narrows to one ticker and that reporting can be scoped to a month or a date range, which implies usage, but never states when to choose this over sibling tools such as dividend_calendar or analyze_ticker. No exclusions or preconditions are given beyond the schema's note that `from` supersedes `month`.

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 closed-world, so the safety profile is covered. The description adds real value beyond that: it discloses the dual data source and the fallback condition, plus the derived concentration metrics, which an agent would not infer from annotations alone.

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

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

A single front-loaded sentence with no filler, and the core scope comes first. It is dense but each clause (source, contents, metrics, share-class rule) earns its place; only the parenthetical metric list is slightly compressed.

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 structure, yet it still usefully enumerates the payload categories. For a two-parameter, read-only lookup tool this covers what an agent needs to call it correctly; only explicit sibling routing is missing.

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

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

Schema description coverage is 100%, and both parameters are fully documented in the schema (ticker examples, limit range and ordering). The description's mention of 'the largest lines with their weights' only marginally reinforces the largest-first ordering already stated in the limit parameter, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource (an ETF's or index fund's holdings) and enumerates what comes back: largest lines with weights, sector mix, and concentration stats. It also names the fallback data source (issuer file vs. SEC N-PORT) and the share-class resolution rule, which clearly separates it from siblings like etf_overlap, who_holds, and fund_fees.

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 context is implied through the data-source fallback (issuer file first, SEC N-PORT for funds outside the catalog) and the share-class resolution behavior. However, there is no explicit guidance on when to pick this over etf_overlap or who_holds, and no exclusions are stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description nonetheless adds genuine behavioral context: the overlap is computed from full issuer holdings files matched on ISIN, which tells the agent the numbers are point-in-time holdings-based rather than price-based, and that tickers must be resolvable by ISIN.

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

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

Two sentences, front-loaded with the definition of the headline metric and its formula in parentheses, then data provenance, then example queries as a routing cue. No filler and nothing repeated from the title 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?

With an output schema present the description needn't enumerate return fields, and it instead defines the metric precisely enough to interpret those fields. The only shortfall is that it doesn't distinguish this from the closest sibling tools (compare, etf_holdings), a minor gap for a simple 3-parameter analytical 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%, with each of fund_a, fund_b, and limit documented including format and bounds, so the baseline is 3. The description only lightly reinforces parameters via "the largest shared holdings" (implying limit shapes that list) without adding format or edge-case guidance 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?

Names a specific resource (two ETFs) and defines the exact computation: overlap by weight as the sum of the smaller weight over commonly held companies, plus shared count, per-fund shared share, and largest shared holdings. An agent can distinguish this from compare or etf_holdings purely from this text.

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?

Ends with quoted example intents ("VOO vs QQQ overlap", "is IVV the same as VOO") that imply when to reach for it, and the ISIN-matched full issuer file note hints at data fidelity. But it never states when NOT to use it or names the sibling (compare, etf_holdings) that handles adjacent questions, so routing is left to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive and open-world. The description adds meaningful behavior beyond them: the ratio provenance (Yahoo Finance's listing of the latest annual report), that no recommendation is made, and that non-fund or unpublished-ratio lines are explicitly named rather than silently dropped.

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?

Single paragraph with the computation and formula front-loaded, followed by caveats. Several parentheticals (the provenance clause especially) make it denser than strictly necessary, 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 need no explanation; the description still covers the calculation, provenance and degradation behavior for unpublished ratios. What is missing is only minor: how the weighted ratio is computed and what happens with mixed or non-USD currencies.

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

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

Schema description coverage is 100%, so ticker, amount, currency and the 50-item cap are all documented in the schema. The description only restates 'funds and amounts the user gives' and adds no format, currency or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a precise verb and resource ('Computes ... what each fund's expense ratio takes a year'), gives the formula (amount × expense ratio), the outputs (per-fund cost, total, weighted ratio) and the data source. This is clearly distinguishable from siblings like etf_holdings or analyze_ticker.

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

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

Ends with an explicit trigger phrase ('Use it for "how much do my ETFs cost me a year"') and frames itself as a fact-finder, not advice. It does not name an alternative tool or state when not to use it, so it falls short of the top score.

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

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

The description adds meaningful behavioral detail beyond the annotations: it states that nothing is stored, that current prices are fetched unless supplied in `prices`, and that wash-sale and tax-treatment rules are applied across every account including IRAs and 401(k)s. It also discloses that funds on the same index are flagged but never judged "substantially identical," which prevents the agent from overreading the output.

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 and the density is justified by the complexity of the tax rules being described. However, the main body is a long, clause-heavy sentence that could be broken up for easier 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?

Given the complex domain, rich input schema, annotations, and output schema, the description is complete enough for an agent to call the tool correctly. It covers residency-specific behavior, wash-sale handling, price fetching, and the fact that no data is stored.

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 nested lot fields, `prices`, `carryover`, `residence`, and `filing_status` are already well documented in the schema. The description adds some high-level context about the lot array and the need to include sales, but it does not add much meaning beyond the structured fields.

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 computes realized losses on user-provided lots for a sale before December 31 and explains what those losses offset. It clearly distinguishes the US and French tax regimes and is unmistakable relative to the sibling tools, none of which are tax-loss harvesting calculators.

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

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

It gives explicit use cases: "how much tax can my losses save before December 31" and "would this be a wash sale." It does not state when not to use it or name an alternative tool, but the context is clear enough that an agent can infer appropriate use.

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/closed-world, and the description adds genuinely new context: data comes from offline issuer files, no market call is made, and 13F figures reflect the latest reported quarter. It stops short of noting lag or coverage caveats (e.g. 13F reporting delay, ETFs outside the 54), which would push it to a 5.

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

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

Front-loaded with the core answer, then the data provenance, then usage examples — a logical order with no filler. The parenthetical clauses are dense but each carries real information; the sentence is long enough that a skim may miss the 13F qualifier.

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 rich annotations, the description only needs to supply scope and provenance, and it does: 54-ETF universe, ISIN matching, latest-quarter 13F, offline/fast. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by constraining the input to a US-listed stock and disclosing that matching happens on ISIN, which tells the caller that non-US listings or ambiguous tickers may not resolve. No format or edge-case guidance for tickers like 'BRK.B' beyond the schema 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?

States a specific question-answering resource: which of 54 tracked US ETFs hold a US-listed stock, plus which famous investors hold it per latest 13F. It names the data sources (issuer holdings files, ISIN match, 13F) and scopes the universe, so an agent can distinguish it from etf_holdings (forward lookup) and analyze_ticker without opening a schema.

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

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

Gives concrete trigger phrases ('which ETFs hold PLTR', 'does Buffett own Apple') that map cleanly onto the tool's purpose. It does not explicitly name a sibling to avoid (e.g. etf_holdings for the reverse direction), so the boundary is implied 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 declare readOnly/idempotent/non-destructive and closed-world; the description reinforces this with "Nothing is stored" and "Countries outside its table are named, never guessed", the latter directly corroborating openWorldHint=false. It also discloses methodology an agent could not infer: statutory rates as of 2026, US 15% with W-8BEN, European funds paying no withholding.

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

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

Front-loads the core computation in the first clause and keeps every later detail (rates, edge cases, no storage) relevant. It is dense and slightly run-on across three long sentences, which keeps it just under a 5.

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

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

An output schema exists so return values need no explanation, and the description covers the remaining gaps an agent needs: rate assumptions, unknown-country handling, no persistence, and residence-specific behavior. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that dividends are gross annual figures identified by ticker or country code and by describing the residence-dependent French 2047 credit treatment. This goes beyond restating field 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?

States a specific verb (computes) and a precisely scoped resource: source withholding, treaty rate, and over-withholding on a per-payer dividend list, plus the French 2047 credit. An agent can tell this apart from sibling tax tools like tax_loss_harvest 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?

Provides concrete user-question triggers ("how much Swiss tax do I lose on Nestlé dividends", "which of my dividends are over-withheld") that make the intended use unambiguous. It stops short of naming an explicit alternative or a when-not-to-use condition, so it sits below a 5.

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