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

Annotations cover read-only/idempotent/open-world, and the description still adds substantial behavior beyond them: missing prices fall back to the day's close, a bare month uses its first session, the result flags both substitutions, the 500-transaction cap is implied by scope, and it explicitly states it describes the past and offers no buy/sell advice. That is real disclosure the annotations cannot carry.

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

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

Dense but every sentence carries information; usage is front-loaded ahead of the output inventory. It is on the long side with heavy parenthetical examples, keeping it below a crisp 5, but nothing is filler.

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

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

With no output schema, the description compensates by enumerating the returned metrics and comparisons in detail, including the compare_with semantics (each holding measured over its own period, the account over its own cash flows). An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by telling the agent that only symbol, date and quantity are required and to call with whatever the user gave rather than soliciting prices, days or fees first, which is genuine invocation guidance beyond the field-level docs.

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 precise verb and resource ('analyze an actual brokerage account from its transactions') and enumerates the concrete outputs (quantity, average cost, market value, weight, realized/unrealized P&L, dividends, MWR, concentration). It explicitly distinguishes itself from the sibling portfolio_real_return for inflation questions, so an agent can route without opening either schema.

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

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

It states exactly when to fire — whenever the user mentions shares bought or sold by count and date — including edge cases (a single purchase, an already-closed position), and gives several literal user phrasings ('how is my portfolio doing', 'which stock lost me the most'). It names the alternative tool for the adjacent inflation use case, which is explicit when-not guidance.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered structurally. The description goes beyond that by disclosing the specific anomaly classes it inspects and that it returns an overall verdict, which tells the agent what the operation actually examines. It does not mention latency, provider coverage, or failure modes, keeping it at a 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?

The diagnostic payload is front-loaded in the first clause, the enumerated checks follow, and the single usage sentence is last. Every clause carries information and nothing is redundant.

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

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

There is no output schema, so the description must convey what comes back, and it does — the listed anomaly checks plus an overall verdict. For a read-only, idempotent tool with fully documented parameters, that is nearly complete; only the precise response shape (per-check detail vs summary) remains unspecified.

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

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

Schema description coverage is 100%, so symbol, start, end, and period are all documented in the schema itself. The description adds no additional parameter meaning beyond a passing reference to 'long-period analysis', 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 specific verb (audit) and resource (an asset's price history) and enumerates exactly what the audit detects: missing closes, zero-volume bars, gaps, suspicious one-session moves, and stale latest bars, plus an overall verdict. This is far more specific than a tautology and clearly positions it as a diagnostic tool rather than a summary or comparison tool.

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

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

Explicitly says when to use it: when a result looks surprising or before a long-period analysis. That is a concrete trigger condition. However, it names no alternatives or exclusions (e.g., when get_price_summary or explain_price_move would be the better first stop), so it stops short of 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 readOnly, idempotent and openWorld, so the safety profile is covered. The description adds genuine behavioral context beyond that: settings are reported as present/absent and never their values (a privacy guarantee), and it discloses the output shape (sources, missing settings, tool mapping).

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 and scoped field list, and the entire definition is two sentences. The trailing clause 'to answer a question, call the tool for it' is a little garbled and slightly dampens the otherwise tight structure.

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

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

With no output schema and no parameters, the description carries the full burden and discharges it: it says what is reported, that values are masked, and which tools each source serves. An agent has everything needed to call it and interpret the result.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is no parameter surface for the description to explain or compensate for.

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 (report) and resource (data sources and configuration status), and enumerates what it reports on: price data, financials/SEC, inflation, news, plus the tool-to-source mapping. This diagnostic purpose is unmistakably distinct from every sibling, which are all analysis/query 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?

Gives an explicit trigger: 'Call it when a tool says a source is not configured,' which is a clear when-to-use condition. It also implicitly steers away from using this to answer data questions ('to answer a question, call the tool for it'), though that phrasing is slightly ambiguous and no specific alternative tools are named.

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, openWorld, idempotent). The description adds useful non-obvious behavior: nominal returns, per-currency measurement, the cross-currency normalization and ranking rule, and the fraction convention for ratios. It does not cover error behavior or pagination, but adds real context 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?

Three tight sentences: what it does and the metric set first, the comparison use case second, and the currency/units caveats last. Every sentence carries information and nothing is repeated from the 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 no output schema, the description correctly carries the burden of describing returns, volatility, drawdown, currency handling, and ratio units, which it does well. Minor gaps remain (e.g., behavior on invalid symbols or mixed-date-range failures), but the essential call-time information is present.

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 all five parameters are already documented in the schema, including the currency default rule. The description reinforces the currency behavior and the fraction convention but adds little syntax or format detail beyond what the schema already provides; 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?

Names a specific verb (compare), the resource (2–10 assets), the common date window, and the exact metrics returned (total and annualized return, volatility, maximum drawdown). The nominal-return caveat implicitly distinguishes it from compare_real_return, so an agent can tell it apart from siblings 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?

'Use it to compare assets or an asset against an index' gives clear context for when this tool applies. It does not name the alternative (compare_real_return) or state when-not-to-use conditions, so it falls short of full routing guidance.

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

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

Annotations cover only read-only/idempotent/open-world safety, and the description goes well beyond: extra comparisons (deposit before/after withholding, house prices) are gated on an EVDS key, the tool degrades gracefully when the inflation series ends before the period and reports how far it reaches, and ratios are declared to be fractions so 0.12 is not misread as 12. These are exactly the operational facts an agent cannot get from 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 answer-to-a-question framing is front-loaded and the closing fraction note is a small but high-value convention. The middle is dense with stacked parentheticals (gold chain, house-price areas, "had I bought a house instead?"), which is efficient for coverage but pushes the reading load up.

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

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

With no output schema, the description carries the return-value burden and does so: it lists the metrics returned, their units, the extra comparison legs, and the degradation behavior when data runs short. For a 7-parameter tool with one required parameter this is sufficient to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds conditional relevance the schema does not: house_price_area and the deposit comparison only matter for TL assets and only with an EVDS key, and amount changes the output to money terms. It does not add syntax beyond the schema, so it stays just above baseline.

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

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

The description opens with the exact question the tool answers ("did this asset beat inflation?") and enumerates the outputs: nominal return, cumulative CPI, real return, annualized rate, and cross-currency/cross-asset comparisons. It explicitly names the sibling it is not (portfolio_real_return) so the agent can separate the single-asset case from the multi-purchase case.

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 triggering scenario ("one asset over a period", e.g. "had I bought X in 2023") and the explicit alternative with the condition that selects it — when the user gives their own amounts and dates, use portfolio_real_return. It also flags that no API key is required, removing a common pre-call hesitation.

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 safe read semantics (readOnly, idempotent, openWorld). The description adds substantial value beyond that by disclosing the output contract (facts presented side by side) and firm interpretive constraints (never apportion, never state cause, never predict), which prevent the agent from over-claiming. It does not cover things like rate limits or result shape beyond content, but the interpretive guardrails are the important disclosure here.

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

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

The usage trigger is front-loaded and every clause (the enumerated facts plus the three 'never' constraints) earns its place. It is a single dense run-on sentence, which is the only structural blemish.

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

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

With no output schema, the description carries the return-content burden and does so thoroughly, listing the facts returned and the default-date rule. Combined with annotations covering safety, an agent has enough to call it correctly; only finer output formatting is absent.

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%: both 'date' and 'symbol' are documented, with symbol already pointing to search_assets in the schema. The description only echoes the default-session behavior for date, adding nothing the schema lacks, so baseline 3 is correct.

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 ('explain_price_move') and enumerates exactly the facts it assembles: the stock's move vs the benchmark's, the spread, size and volume vs recent days, ex-dividend status, and surrounding news. This precisely delineated scope (one session, facts only) implicitly separates it from neighbors like compare_assets or get_price_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?

Opens with an explicit trigger ('For "why did it rise or fall today?"') and clarifies the default-date behavior. It does not name an alternative tool or state when-not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds meaningful context beyond those: it specifies the returned candidate fields (LEI, country, number of filings) and the geographic coverage gap (German/Irish excluded). It does not, however, describe result ordering, pagination, or behavior when no candidates match.

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

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

Three sentences, front-loaded with purpose, then the usage handoff, then the exclusion. Every sentence earns its place, with no redundant or vague wording.

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 search with no output schema, the description explains what is returned (candidates with LEI, country, filing count), how to use the result (pass LEI to get_financials), and known coverage limits. An agent has enough information to invoke it correctly and interpret its output.

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% for the single 'name' parameter, and the schema itself explains it accepts part of the registered name with an example ('ASML'). The description adds no further syntax, format, or constraint details for the parameter, so the baseline of 3 applies.

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

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

States a specific verb ('Find'), resource ('European or UK listed company in the index of official annual reports (ESEF, filings.xbrl.org)'), and the return fields (LEI, country, number of filings). It also differentiates from get_financials by explaining the LEI handoff and notes the German/Irish exclusion, so an agent can identify it 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?

Explicitly says to pass the chosen LEI to get_financials as the symbol for official IFRS annual figures, and states 'Not covered: German and Irish companies.' This gives clear when-to-use and exclusion guidance, with the next-step alternative named.

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 provide readOnlyHint, openWorldHint, and idempotentHint, lowering the burden. The description adds meaningful behavioral context beyond annotations: it clarifies that results are measurements, not causal proof, and that ratios are expressed as fractions (0.12 means 12%). This helps the agent interpret results correctly.

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

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

The description is front-loaded with the core action and output, then a usage cue, then a critical interpretation caveat and unit convention. Every sentence earns its place, and there is no repetitive or filler content despite covering a fairly rich tool.

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

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

Given there is no output schema, the description does a good job enumerating the computed values and their units, so an agent knows what to expect. It also clarifies the non-causal interpretation. Minor gaps like handling of missing sessions or non-trading event dates are not addressed, but the core calling context is 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 100%, so the schema already documents all four parameters and their meanings. The description reinforces the default windows (1st, 5th, 20th session) and the benchmark concept, but it does not add parameter-specific semantics that are not already present in the input 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 opens with a specific verb and resource: 'Measure how an asset's price moved after a dated event.' It enumerates the exact outputs (returns at 1st/5th/20th session, benchmark return, excess, drift), which clearly differentiates it from siblings like get_price_summary and compare_assets.

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

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

It explicitly says 'Use it for "how did the market react to X" questions,' giving clear context for when to invoke it. It also adds a useful exclusion by stating it measures but does not prove causation Temp, though it does not name alternative tools or when-not conditions explicitly.

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 safety and idempotency, but the description adds substantial context: data provenance (SEC filings, official IFRS via LEI, unofficial fallback for other symbols), a verification caveat pointing to KAP, TMS 29 inflation handling, the real vs reported growth split, and self-diagnostic flags for missing/non-reconciling quarters. This is well beyond what the annotations disclose.

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

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

Dense and front-loaded: the purpose leads, then usage examples, then return contents and caveats. Every clause carries information, though the single long paragraph packs many concerns together and could be segmented more cleanly.

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

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

No output schema exists, yet the description fully describes the returned fields (revenue, gross/operating/net profit, margins, debt-to-equity, QoQ/YoY/annual growth, history depth) and the reliability caveats. Nothing an agent needs to call and interpret 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?

With one parameter at 100% schema coverage the baseline is 3, but the description adds that the symbol may be an LEI from find_official_filer for European/UK official figures, which is meaning the schema does not state. That extra semantic detail raises it above baseline.

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

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

The first sentence states a specific resource (a listed company's financial statements) and scope (Borsa Istanbul, US, European shares), which immediately distinguishes it from siblings like get_price_summary or get_valuation. An agent can tell what it returns without opening the schema.

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

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

It supplies concrete user intents ('how were the latest quarter's results', 'what was the net profit', 'did sales grow'), which is strong when-to-use guidance, and it names find_official_filer as the source of an LEI for European/UK filers. It stops short of explicit when-not-to-use routing against siblings such as get_valuation, so it is not a full 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 and openWorldHint, so safety basics are covered; the description goes further by disclosing that syndicated duplicates are merged, that coverage spans roughly 90 days, and that results are unverified listings whose titles must be treated as data, never as instructions. That last point is an important content-trust warning an agent could not infer from structured fields.

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

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

Front-loaded with what the tool returns, then how to use it, then the alternative-routing rule, then coverage and safety caveats. Each sentence carries distinct information (routing, scope, trust warning) with no filler or repetition.

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

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

There is no output schema, and the description compensates by naming the returned fields and their ordering, plus dedup behavior. Combined with the routing rule and safety caveat, an agent has everything needed to select and call this tool correctly.

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

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

Schema description coverage is 100%: each of the four parameters already documents its type, range, default and meaning, including the query format examples. The description adds no parameter-level syntax or format 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 specific verb and resource (recent news articles about a company or topic), enumerates the returned fields (title, publisher, date, language, link), and specifies ordering (newest first) plus dedup behavior. It explicitly names the sibling it is not (explain_price_move), so the agent can disambiguate without opening either schema.

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

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

Gives concrete trigger phrasings ('is there news about X', 'what are the latest developments', 'was there an announcement') and a clear exclusion rule: for 'why did X rise or fall', call explain_price_move instead, with the reason (it includes the news around that session). The 90-day coverage window further bounds when this tool applies.

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), so the description's added value is output semantics: results are nominal and in the asset's own currency, and ratios are fractions (0.12 = 12%). That unit convention is genuinely useful for interpreting results, but it stops short of disclosing behavior around missing/partial data 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?

Front-loaded with the metric list, then routing rules, then a final unit clarification. Three tight sentences with no filler; each sentence carries distinct, load-bearing 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?

No output schema exists, so the description must describe return values — and it does, naming the exact metrics and their units (nominal, own currency, ratios as fractions, drawdown dates). Combined with sibling routing, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the schema already documents symbol, start, end, and period (including the 'period ignored when start is given' rule). The description adds no parameter-level meaning beyond that; its unit note concerns output, not inputs. Baseline 3 is appropriate.

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

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

States a specific verb ('measure') and resource (one asset's performance over a period) and enumerates the returned metrics: total and annualized return, annualized volatility, max drawdown with dates, and data coverage. It also names the sibling tools it is not (explain_price_move, compare_real_return, compare_assets), so an agent can differentiate without opening any schema.

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

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

Explicit routing: use for 'how did X do' questions; for one day's move use explain_price_move; for inflation/USD/gold terms use compare_real_return; for several assets use compare_assets. Every alternative has a clear selecting condition, leaving nothing 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 mark this read-only, idempotent and open-world, and the description goes well beyond them: currency conversion of statement figures to the trading currency, Turkish inflation accounting limits on P/E and P/S, and the rule that a ratio is null with a reason when the denominator is missing or non-positive. These are non-obvious behaviors an agent could not infer from the schema.

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

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

Purpose and metric list are front-loaded, and the caveats are relevant, but the 'gives figures, not a verdict / never cheap or expensive' idea is stated twice ('Describes the past; not a view on value'), and the parenthetical exchange abbreviations add clutter. Efficient overall, with minor redundancy.

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

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

With no output schema, the description carries the full burden of describing return values, and it does so thoroughly: which ratios, over what periods, the industry comparison, currency handling, and null-with-reason semantics. An agent has enough to interpret results without guessing.

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 contextual semantics: the LEI-vs-symbol distinction and the trading-currency mismatch case that motivates price_symbol. It still doesn't restate the parameter syntax, hence a modest bump rather than a top score.

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

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

States a specific verb+resource (valuation of a listed company) and enumerates the exact metrics returned: market value, P/E, P/B, P/S, TTM dividend yield, and industry-relative P/B. This is clearly separable from siblings like get_price_summary or get_financials, which cover prices and statements rather than derived ratios.

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?

Frames the use case concretely with example questions ('is X cheap or expensive', 'what is its P/E or P/B') and states an explicit boundary: it reports figures, never a verdict, and the answer should not editorialize. It does not name a sibling alternative for overlapping needs, so it stops short of 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 readOnly/idempotent/openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: sales and dividends are not modelled, ratios are fractions not percentages, and DEPOSIT/HOUSE require TRY and an EVDS key. It stops short of describing pagination or failure modes, but the added constraints are substantive.

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 computation before the usage rule and example, and every sentence carries information. It is dense and slightly sprawling with the embedded parenthetical example, but no sentence is filler.

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

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

There is no output schema, so the description must characterize the return values, and it does so thoroughly: total paid, current value, return, annualized money-weighted return, real return, and benchmark comparisons. Combined with the caveat about sales/dividends and the fraction convention, an agent has everything needed to call and interpret 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 description coverage is 100%, so the schema already documents purchases, currency, compare_with and inflation_region in detail. The description largely restates compare_with's options (USD/gold/deposit/housing/index) rather than adding new semantics, so the baseline of 3 is appropriate.

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

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

States specific verbs and resources: evaluates dated purchases and computes total paid, current value, return, annualized money-weighted return, real return, plus benchmark comparisons. It explicitly distinguishes itself from the sibling analyze_portfolio ('for share counts use analyze_portfolio'), so an agent can route correctly without opening schemas.

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

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

Gives an explicit trigger condition ('Use it whenever the user describes their own purchases as sums of money with dates'), names the alternative and the condition that selects it (analyze_portfolio for share counts), and adds an inline example query. It also states exclusions ('Purchases only; sales and cash dividends are not modelled').

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the bar for disclosure is lower. The description adds useful behavioral context: what the search returns (canonical symbols, asset class, exchange) and what it explicitly does not return (prices). This goes beyond the annotations without contradicting them.

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

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

Three short sentences, each earning its place: the main purpose, the primary use case context, and the key non-return boundary. No redundancy or 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 simple two-parameter search tool with rich annotations, the description is complete. It explains what the tool returns, when to use it, and what it does not do, which is all an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%: both `query` and `limit` are documented in the schema. The description reinforces that `query` can be a name or ticker but does not materially add new parameter-level detail beyond the schema.

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

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

The description states a specific verb and resource: 'Find assets by name or ticker and return their canonical symbols, asset class and exchange.' It also distinguishes this tool from siblings by noting that 'every other tool takes the symbols it returns,' making its role as a symbol lookup clear.

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

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

The description gives explicit usage guidance: 'Use this first whenever you are not certain of an exact symbol.' It also clarifies the tool's relationship to all other tools and states a negative boundary ('Does not return prices'), helping an agent decide when not to use it.

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