opula

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

Annotations (no readOnly/destructive hints) are supplemented with detailed behavioral context: upsert semantics (overwrites same composite key), return values for single vs multi-entry, book vs live market distinction, no double-counting, and currency conversion.

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

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

Well-structured with front-loaded main action, but the category list is duplicated from the schema, making it slightly verbose. Could be more concise without losing critical clarification.

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?

Thorough coverage despite no output schema: explains return values for single and multi-entry, handles edge cases (non-USD, multiple entries), disambiguates from siblings, and provides conceptual model (book vs live). Essential for a complex 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?

Despite 100% schema coverage, the description adds substantial meaning: explains entries array usage, provides the full category list with sub_type pairs, emphasizes stocks belong here, clarifies book vs live separation, and details non-USD handling. This exceeds baseline 3.

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

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

The description clearly states the tool upserts balance sheet entries (verb 'Upsert', resource 'balance sheet entries'). It distinguishes from sibling 'add_monthly' by indicating preference for month-end settlement, and references 'show_categories' for the catalog.

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

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

Provides explicit guidance to prefer add_monthly for full month-end settlement, explains when to use single vs multi-entry, and covers non-USD currency handling. Lacks explicit 'do not use when' but guidance is clear and actionable.

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

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

Discloses upsert behavior, cash basis accounting, and return behavior (single vs multi-entry). No contradiction with annotations (readOnlyHint=false, destructiveHint=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 main verb and structured paragraphs, but somewhat lengthy due to detailed explanations of cash basis and categories. For a complex tool, this is acceptable.

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 all aspects: usage, parameters, categories, accounting basis, return behavior. No output schema needed as return is described.

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

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

Schema coverage is 100% with detailed field descriptions. Description adds context on array usage, composite key, and currency conversion, but the schema already provides comprehensive parameter info.

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

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

The description clearly states the tool upserts cash flow entries, including editing via composite key. It distinguishes from siblings like add_monthly and references show_categories for catalog.

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 advises preferring add_monthly for full month-end settlement and warns against inventing categories, directing to show_categories. Also explains cash basis versus accrual accounting.

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 readOnlyHint=false and destructiveHint=false are consistent with the described upsert operation. The description goes beyond by explaining the data source (book-based net worth), the separation from live portfolio via get_market_brief, and the treatment of stocks at settlement. No contradictions.

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

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

The description is long but well-structured: it opens with the primary purpose, then usage guidelines, then category lists, and finally behavioral notes. While verbose, every sentence adds value. The front-loading is effective.

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

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

Given the complexity (4 parameters, nested arrays, no output schema), the description fully covers the tool's role, workflow, category constraints, and relationships to other tools (get_market_brief, get_wealth_brief). It addresses potential confusion like double-counting of stocks.

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 50%, but the description substantially compensates by listing all valid categories and sub_types with examples, explaining the purpose of sub_type, and providing additional context (e.g., usd_cash should use sub_type=cash). This adds significant meaning 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 clearly states 'Batch upsert balance and flow entries for a single period in one call' and labels it as the 'Primary tool for month-end settlement.' It effectively distinguishes from sibling tools like add_balance and add_flow by emphasizing batch and period-specific use.

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

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

The description provides explicit when-to-use guidance: 'When the user says "month-end closing" or "record this month"…' and outlines a step-by-step procedure including calling show_categories, confirming numbers, and post-call use of get_wealth_brief. It also warns against inventing categories and clarifies when not to just display 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?

Annotations provide readOnlyHint=false (write operation) and destructiveHint=false (non-destructive). The description adds critical behavior: currency conversion to USD, date stamping (latest wins), and impact on downstream tools like get_market_brief and show_portfolio. No contradictions.

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

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

The description is concise (5 sentences) and well-structured. It front-loads the core purpose ('Set the current price of ONE non-stock asset') and then elaborates logically on scope, matching, value semantics, and usage. No unnecessary words.

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

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

Given the tool has 3 parameters, no output schema, and no nested objects, the description covers everything needed: purpose, applicable assets, matching rules, price meaning, currency handling, effect on other tools, and repetition policy. It is fully self-contained.

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 significant extra meaning beyond the schema: name is case-insensitively matched to holdings, value is per share/unit, currency default and conversion explanation, and mention of 'free-form ticker'. This enriches the schema descriptions.

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

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

The description clearly states the tool sets the current price for one non-stock asset, listing supported types (crypto, commodity, real_estate, other) and explicitly distinguishes it from stocks, which are auto-priced. The verb 'Set' and resource 'price of a non-stock asset' are specific, and it differentiates from siblings like add_balance or show_portfolio.

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

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

It explicitly states when to use this tool: for non-stock assets manually valued, and when not to use it: for stocks, which will return an error. It also advises calling it again on new valuation. This provides clear context and exclusion criteria.

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

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

Annotations only indicate read/write nature. The description adds rich behavioral details: rows sorted by date, USD conversion at transaction date, per-type behavior (buy/sell vs deposit/dividend/tax), and market vs non-stock asset handling. No contradictions with annotations.

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

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

The description is long but well-structured with clear context on bulk imports and reason capture. While every sentence serves a purpose, it could be slightly more concise. The front-loading is good but not perfect.

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

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

Given the complexity (nested array, multiple transaction types, asset classes, currency handling) and no output schema, the description is remarkably complete. It covers all edge cases, workflows, and constraints, leaving little ambiguity for an AI agent.

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

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

Schema coverage is 100%, but the description adds significant context beyond schema: explains the reason field's importance, how asset_type splits flows, currency usage for non-stock, and market enumeration semantics. This adds substantial value beyond the basic schema.

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

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

The description clearly states the tool inserts transactions in a single call ('Insert one or more transactions in a single call'). The verb 'insert' and resource 'transactions' are specific. However, it does not explicitly differentiate from sibling tools like add_balance or add_price, though the context of transactions is distinct enough.

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

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

The description provides extensive usage guidance: bulk import workflow (show column mapping, wait for confirmation), single trade reason capture (with explicit when to ask/skip), sorting behavior, and asset type-specific instructions. It covers when to use this tool vs. not, making it highly actionable.

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 confirm destructiveness; description adds period-scoped deletion detail but no further behavioral disclosure (e.g., irreversibility, cascade effects).

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

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

Two efficient sentences, front-loaded purpose, zero wasted words.

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

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

Adequate for a simple deletion tool with annotations covering destructiveness; could mention return status but not critical.

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%, baseline 3; description adds value by explaining conditional behavior (category controls single vs. bulk deletion).

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?

Clear verb+resource ('Delete balance entries') and distinguishes behavior with/without category, unlike sibling delete_flow or delete_txn.

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 context for two usage modes (with/without category) but no explicit when-not-to-use or alternatives like delete_flow.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds crucial context about the period-bound deletion and the conditional behavior of category, which is important for understanding the destructive scope. No contradiction with annotations.

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

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

Two sentences, each adding essential information without redundancy. Efficient and front-loaded.

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

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

For a destructive tool with annotations, the description fully covers the delete behavior, conditional modes, and period constraint. No output schema is needed for a delete operation. Complete within the context.

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

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

Schema has 100% coverage, so description is not required to repeat parameter details. However, it adds value by explaining the interaction between period and category, and implicitly clarifies that type and sub_type are required when category is provided.

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

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

The description clearly states the action ('delete flow entries') and resource ('flow entries for a period'), with explicit conditional behavior based on category. It distinguishes from sibling delete tools like delete_balance and delete_txn by specifying 'flow entries'.

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

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

The description provides clear guidance on when to provide category (to delete a single entry) and when to omit it (to delete all entries for the period). It doesn't explicitly compare with alternative tools, but the conditional logic is well explained.

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 descriptions adds value beyond the destructiveHint annotation by explaining the downstream effects: recalculating positions and average cost. It also emphasizes user confirmation. This fully informs the agent of behavioral traits.

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

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

Two sentences: the first states the primary action, the second adds critical usage constraint and behavioral context. No wasted words, front-loaded.

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

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

Given the simple schema (one required param) and annotations (destructiveHint=true), the description covers the necessary context: deletion, user confirmation requirement, and impact on derived data. No missing information.

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 only parameter (id) is not described in the schema (0% coverage). However, the description mentions 'by its id' which identifies the parameter's role. For a single, simple integer parameter, this is sufficient marginal value.

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

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

The description clearly states the action ('Delete a single transaction by its id') and specifies the scope ('single transaction'). It distinguishes from sibling tools like delete_balance and delete_flow by focusing on transactions and mentioning recalculation of positions and average cost.

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

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

Explicitly states the user must confirm and never call without explicit instruction, with an example ('delete transaction #42'). This provides clear guidance on when to use. No alternative tools are mentioned, but the instruction is strong for a destructive action.

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

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

Annotations only indicate mutation and non-destructiveness. Description adds key behavioral details: partial update semantics, parameter coupling for amount/currency, memo clearing via null, historical FX reconversion, and error on missing key.

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

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

The description is a single paragraph with logical flow (purpose, usage, parameter rules, behavior). Each sentence adds value, though it could be slightly more structured with bullet points for complex parameter rules.

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 8 parameters, no output schema, and many sibling tools, the description covers all necessary aspects: purpose, usage, parameter coupling, behavior on success/failure, and return value (updated entry). It is complete for an agent to invoke 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?

Despite 100% schema description coverage, the description adds valuable context beyond schema: e.g., date's role in FX reconversion, amount/currency coupling conditions, memo explicit set vs clear behavior.

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

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

The description clearly states 'Partial update of a single balance entry' and identifies the composite key. It explicitly distinguishes from sibling 'add_balance' by stating when to use it instead.

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

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

Provides explicit when-to-use ('when changing one field on an existing entry'), when-not-to-use (use add_balance for new entries), and gives an example (fixing a typo in memo). Also explains parameter coupling rules.

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 discloses all behavioral traits: partial update, parameter constraints (amount+currency must be together, omitting preserves USD), memo clearing via null, FX reconversion behavior. No contradiction with annotations (readOnlyHint=false, destructiveHint=false). Annotations are consistent with update operation.

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

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

The description is a single focused paragraph with no wasted words. It front-loads the purpose and key constraint, then details parameter behaviors. Every sentence provides necessary information.

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

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

Given the tool's complexity (8 parameters, composite key, dependent fields, FX behavior) and no output schema, the description covers all aspects: what it does, when to use, parameter rules, and return behavior. Complete enough for an agent to use 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 description adds significant meaning beyond schema descriptions: explains composite key identification, dependency between amount and currency, effect of omitting them, and memo clearing. This helps agent correctly invoke the tool.

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

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

The description clearly states it's a partial update of a single flow entry identified by a composite key. It uses a specific verb ('partial update') and resource ('flow entry'), and explicitly distinguishes from sibling tool add_flow by stating when to use each.

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

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

The description explicitly says when to use this tool ('changing one field on an existing entry') and when not ('not add_flow'). It also provides detailed guidance on parameter dependencies (amount+currency together, memo null to clear) and error condition ('errors if no row matches the key').

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 (readOnlyHint=false, destructiveHint=false) are consistent. The description discloses side effects like price conversion to USD, clearing market for asset type changes, and interaction between currency and market, going well beyond annotations.

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

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

The description is concise (~120 words), front-loaded with the core purpose, and uses two focused paragraphs for special behaviors without redundancy.

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

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

Given the complexity (10 params, 4 enums, no output schema), the description covers essential behavioral details but could be improved by mentioning the response format or confirming that updates are persisted.

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 60% schema coverage, the description adds meaning by explaining the conversion date for price, the logic for market clearing, and the hierarchy of currency/market/asset_type, which are not evident from the schema alone.

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

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

The description clearly states 'Update fields of an existing transaction by id' with a specific verb and resource, distinguishing it from siblings like add_txn (create) and delete_txn (delete).

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

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

The description implies usage for modifying a transaction but does not explicitly specify when not to use it or provide alternatives beyond referencing add_txn's fork behavior.

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?

Description adds beyond readOnlyHint: notes deterministic rule-derived facts, no forward-looking probabilities, no caller assumptions. Discloses self-refreshing daily cache, manual sync not required. No contradictions with annotations.

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

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

Long but necessary due to comprehensive output. Lists many components in a semi-structured bullet-like format. Could be more concise, but efficient for the 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?

No output schema, but description thoroughly enumerates return bundles (portfolio, concentration, diversification, movers, etc.) and includes meta. Covers all needed context for an agent to understand what is returned.

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 100%, but description adds context: display_currency default USD, refresh bypasses cached brief. While schema already defines, description reinforces meaning and usage.

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

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

Clearly states it is a diagnostic composite read for current market and portfolio state. Distinguishes from sibling 'get_wealth_brief' by contrasting with net-worth, savings, etc. Uses specific verb 'call' and resource 'market & portfolio state'.

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 call (market, portfolio, regime, 'what should I do' questions) and when to use alternative ('get_wealth_brief'). Also mentions 'show_*' tools are drill-downs, providing clear context.

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

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

Beyond the `readOnlyHint` annotation, the description discloses that returns are 'deterministic rule-derived facts only', money fields use `display_currency` (default USD) and are null when no FX rate is cached, and that `cagr_actual` is null until the ledger spans 12 months. This adds significant behavioral context.

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 lengthy but well-structured, with clear bullet-like definitions for each bundle. It effectively front-loads the core purpose in the first sentence, though some details could be streamlined for easier skimming.

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

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

Given the tool's complexity (multiple bundles like net_worth, cash_flow, etc.) and no output schema, the description comprehensively explains what each bundle contains, ensuring an agent has sufficient context to invoke 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?

With full schema description coverage (100%), the parameter `display_currency` is already well-documented. The description adds the default value explicitly, which aligns with the schema but doesn't provide further semantic enrichment 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 clearly states the tool provides an 'All-in-one structural read of the user's whole-wealth picture' focused on the manual ledger, distinguishing it from siblings like `get_market_brief`. The verb 'get' and resource 'wealth brief' are specific and unambiguous.

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

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

The description explicitly guides when to use this tool vs. alternatives: it notes that the live portfolio lives in `get_market_brief` and explains how to include stock portfolio value via balance entries. This provides clear context for selecting the appropriate tool.

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

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

The description explains the Monte Carlo process, seed behavior, target_value effects, and path_resolution trade-offs. It aligns with readOnlyHint as a thought experiment; no contradictions. It adds value beyond annotations.

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

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

The description is dense and well-structured but somewhat long. It front-loads the core purpose, and each sentence adds value. Minor redundancy (horizon_months range repeated). Overall efficient for 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?

Given 11 parameters, no output schema, and minimal annotations, the description covers all essential aspects: usage context, parameter interactions, output details, and sibling differentiation. No gaps in information.

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 significant extra meaning: explaining how seed ensures reproducibility, how target_value modifies output (probability and median months), and how path_resolution affects payload. It enriches parameter understanding.

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

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

The description clearly states it is a forward-looking Monte Carlo projection tool for net worth, specifying the verb (project), resource (net worth), and method (Monte Carlo, GBM, multi-scenario). It distinguishes itself from siblings like get_market_brief (current state) and simulate_scenario (different approach).

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

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

The description explicitly tells when to use this tool versus alternatives: 'For *current* portfolio state, use `get_market_brief`' and suggests using brief.risk_summary for historical scenarios. It provides clear context and exclusions.

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?

Annotation declares readOnlyHint=true, implying no state modification, but the description describes redeeming a code and granting Pro, a clear mutation. This contradiction misleads the agent about the tool's side effects.

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

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

Two concise sentences that deliver the purpose, usage scenario, and expected outcomes without any filler. Front-loaded with the core action.

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?

While the description explains return outcomes, it omits important behavioral context such as whether the operation is reversible or if authentication is required. The contradiction with annotations further undermines completeness.

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

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

The input schema has 100% coverage with a description for 'code'. The tool description adds context that the code is a one-time coupon from a crowdfunding reward, enhancing understanding 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 clearly states the tool redeems a one-time coupon code to unlock Opula Pro, with specific context about usage. It is distinct from sibling tools which focus on showing data or adding other resources.

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 tells when to use: when the user has a coupon. It also outlines return outcomes. However, it lacks explicit guidance on when not to use or alternatives, but the context is adequate.

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

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

Discloses partial update behavior, storage details (target_net_worth stored as USD), field constraints (4-digit years), and enumeration values (risk_tolerance). No contradiction with annotations (readOnlyHint=false, destructiveHint=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?

Concise 4-sentence description, front-loaded with purpose. Every sentence adds value without redundancy.

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

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

Covers partial updates, field constraints, and storage behavior. Minor gap: does not describe return value (e.g., updated profile object), but no output schema exists to compensate.

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?

Adds significant meaning beyond schema: clarifies 4-digit year format, default currency, and free-form notes. All 8 parameters are described; schema coverage is 50% but description compensates fully.

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

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

Description starts with 'Update the user's profile,' which is a specific verb+resource. It clearly distinguishes from siblings like show_profile (read) and other mutation 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?

States 'Partial updates, only provided fields are changed. All optional; capture only what the user volunteers.' Provides clear context for when to use, but does not explicitly mention alternatives or when not to 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 indicate readOnlyHint=true. The description adds value by listing returned data (counts, plan, profile, next_steps) and reinforcing it's a diagnostic with no side effects. No contradictions.

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

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

Three sentences with clear, front-loaded purpose. Each sentence provides distinct value: purpose, usage, returns. No 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?

Given no parameters and a read-only annotation, the description sufficiently covers what the tool returns (data counts, plan, profile, next_steps) for a diagnostic tool. No output schema exists, but the description is adequate for an agent.

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

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

No parameters exist, so no param info is needed. Baseline for 0 parameters is 4. The description doesn't need to add meaning 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 clearly defines it as a 'One-shot setup diagnostic' and specifies exact scenarios: at conversation start, when unsure about ledger data, or when user asks about plan/billing/cancel. It distinguishes from sibling tools like show_balance or show_profile by being a broad diagnostic.

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

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

Explicitly states when to call: start of conversation, when unsure, or on plan/billing queries. Implies not to use for single-item queries, and 'One-shot' suggests it's only needed once.

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

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

Annotations declare readOnlyHint=true, which the description does not contradict. The description adds valuable behavioral details: data source (cached price series), labeling logic (missed_rebound, good_call, etc.), and handling of missing prices (no_price_data).

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

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

The description packs substantial information into two sentences without redundancy. It is well-structured but slightly dense, which could be improved for quicker comprehension.

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

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

Despite the absence of an output schema, the description fully explains the return format, including field names and label logic. Parameter coverage is complete, and the description provides sufficient context for the AI agent to use the tool correctly.

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

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

The input schema already provides full descriptions for both parameters (limit and display_currency). The description does not add additional semantic value beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as tracking post-exit performance of fully sold positions, specifying the returned data fields and classification labels. It distinguishes itself from sibling tools like show_thesis_track.

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

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

The description states when to use (contemplating a sell or reviewing past decisions) and suggests pairing with show_thesis_track. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true. Description adds detail on response structure (type, sub_type, category, amount, date) and behavior with/without period, providing context beyond annotations.

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

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

Two concise sentences front-load the purpose and provide essential details without any fluff 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?

Without an output schema, the description adequately describes the response fields and period behavior. Could mention if results are returned as a list or any ordering, but overall 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 coverage is 100%, so baseline is 3. Description adds value by explaining the effect of period and listing possible display_currency values, reinforcing meaning beyond schema.

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

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

The description clearly indicates the tool shows balance sheet entries, distinguishing it from CRUD siblings like add_balance and delete_balance. However, it lacks an active verb like 'Returns' or 'Lists', and could more explicitly contrast with other show_* tools.

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

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

Provides useful guidance on using the tool with or without the 'period' parameter for trends vs. snapshots. Does not explicitly address when to use this tool over other show_* tools or state that it is read-only, though annotation helps.

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=true; description adds valuable behavioral details: uses daily snapshot history when ≥2 snapshots exist, else fallback to cost-basis vs current value, and mentions keyless Yahoo data. No contradictions.

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

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

Two sentences, front-loaded with main action, no wasted words. Efficient and easy to parse.

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

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

For a tool with 3 optional parameters and no output schema, the description covers fallback behavior, data source, and return information (per-benchmark return and alpha). Complete enough for an agent.

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

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

Schema coverage is 100% (all three parameters described). Description adds default benchmark tickers and context on date defaults, but does not enhance parameter semantics 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 uses specific verb-resource ('Compare portfolio return against benchmark indices') with default values (SPY, QQQ) and differentiates from sibling tools which are mostly about other aspects of portfolio (e.g., show_portfolio, show_risk).

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?

Clearly states the tool's purpose but does not explicitly mention when not to use it or suggest alternative tools for comparing other metrics. However, the purpose is self-evident and distinct from siblings.

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

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

Adds context beyond the readOnlyHint annotation by explaining the Korean labels, checklist grouping, and strictness about using only these pairs.

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 with clear front-loaded purpose, though the enumeration of examples could be slightly trimmed without losing meaning.

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?

Fully explains what the tool returns, how to present it, and when to use it; no output schema needed given the simplicity of a static catalog.

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 zero parameters, the description adds value by explaining the tool's output and use case, meeting the baseline of 4.

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

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

The description clearly states that the tool provides the canonical ledger category catalog with every valid combination for add_balance, add_flow, and add_monthly, distinguishing it from sibling tools which perform mutations.

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 instructs to call this before asking for balances or cash flow, and to use it as a reference to avoid inventing new category pairs.

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 explains many behavioral details beyond the readOnlyHint annotation: nullability of fields based on sync, the look_through feature expanding ETFs, its caveat (top-10 approximation), and the Pro restriction on risk/forward data. No contradictions with annotations.

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

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

The description is dense but front-loaded with the main output. Some redundancy exists (e.g., mentioning get_market_brief twice), but it remains efficient given the complexity of the output.

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

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

Given no output schema, the description thoroughly explains what the tool returns, including edge cases (null correlation fields, look_through expansion, caveat). It covers all necessary information for an agent to understand the tool's 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?

The tool has no parameters and schema coverage is 100%, so the description does not need to add parameter semantics. Baseline 4 applies as there is nothing to improve.

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

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

The description clearly states the tool computes portfolio concentration using HHI across ticker, sector, and country, with additional metrics like effective-N and correlation matrix. It distinguishes itself from get_market_brief by specifying that this is the drill-down when only concentration is asked for.

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

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

The description provides usage context: it explains effective_n/correlation matrix are null until sync populates cache, and directs to use this tool when only concentration is requested. It references get_market_brief as an alternative for broader market data, but does not explicitly list other exclusions or when-not-to-use scenarios.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by disclosing that the data is estimated, based on a price cache, and only includes tickers with dividend data. No contradictions with annotations.

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

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

The description is extremely concise, consisting of two sentences that pack essential information without any unnecessary words. It is front-loaded with the core purpose.

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

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

Given the tool's simplicity (one optional parameter, read-only, no output schema), the description adequately covers what the tool does and its limitations. It could mention the return format for completeness, but still meets the needs for a straightforward dividend display tool.

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

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

Schema coverage is 100% for the single parameter 'display_currency', which has a clear description and default. The description mentions the currency and default, but does not add significant new meaning 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 clearly states the tool returns estimated annual dividend income, including per-ticker yield, annual dividend-per-share, and estimated income in a specified currency. It specifies that only tickers with dividend data are included, distinguishing it from other 'show_*' tools like 'show_earnings' or 'show_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?

The description indicates when to use it (to view dividend income), but does not explicitly mention when not to use it or provide alternatives. Context from sibling tools helps but is not explicitly tied to this tool's description.

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 states the read-only behavior (consistent with annotations' readOnlyHint) and the conditional output based on ticker presence. However, it does not disclose details like data sources, update frequency, or potential limitations (e.g., only for US markets), which would add value beyond annotations.

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

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

The description is optimally concise: two sentences that front-load the core purpose and immediately follow with operational details. Every sentence contributes essential information without redundancy.

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

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

Given the tool's moderate complexity (three optional parameters, no output schema), the description reasonably covers the two main usage modes. It omits output format details, but since there is no output schema, this is acceptable. A minor gap is not mentioning any caveats like exchange coverage or data freshness.

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

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

All three parameters have schema descriptions, so schema coverage is 100%. The description adds value by explaining the behavioral implications: omitting ticker returns all holdings, providing ticker enables history. This goes beyond the schema's parameter-level descriptions.

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

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

The description clearly identifies the tool as an earnings calendar, explaining that without a ticker it returns upcoming earnings for all held tickers, and with a ticker it returns history plus upcoming. This distinguishes it from many sibling 'show_*' tools like show_dividend or show_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?

The description provides explicit guidance on when to use the tool with or without a ticker parameter, and mentions the history flag for past quarters. It does not explicitly mention alternatives or when not to use it, but the context is clear enough for typical use cases.

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

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

Annotations indicate readOnlyHint=true, and description adds behavioral context: quarterly figures are discrete single-quarter values, covers US and non-US listings. No contradictions. Could mention that data is point-in-time or sourced from filing dates.

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, each earning its place. First sentence defines purpose and scope, second clarifies quarterly data handling and geographic coverage. No redundant information.

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

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

Given three parameters and no output schema, description adequately covers what metrics are provided and data granularity. Could elaborate on limit's effect or default behavior, but overall complete for its complexity.

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 description mentions ticker and 'per period' linking to freq and limit, but does not explain the freq enum values or limit's full meaning beyond schema. With 67% schema coverage, description partially compensates but leaves 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 description clearly states it shows financials (income statement, cash flow, balance sheet) for a ticker per period. This distinguishes it from sibling tools like show_balance (balance only) or show_flow (cash flow only), making the purpose unambiguous.

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

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

The description implies usage for retrieving financial metrics but does not explicitly state when to use this tool over alternatives like show_macro or show_valuation. It lacks when-not guidance or prerequisite conditions.

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

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

Annotations already declare readOnlyHint=true, and description adds details on data structure, period filtering, and currency, providing context beyond annotations without contradiction.

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

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

Three sentences: data description, period behavior, alternative tool. No fluff, well-structured and front-loaded.

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

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

Covers return fields and period usage adequately. Lacks mentions of pagination or ordering, but acceptable for a simple read-only tool with no output schema.

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 description adds usage context (behavior with/without period) that clarifies parameter semantics beyond schema descriptions.

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

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

Description clearly states it shows monthly cash flow entries with specific fields (type, sub_type, category, amount, date) and distinguishes from sibling get_wealth_brief for trend analysis.

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

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

Explicitly describes behavior with/without period and suggests alternative for trend analysis. However, does not compare to other list tools like show_txns, but the main alternative is covered.

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

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

Discloses fallback behavior with lookback_days, the base currency special case, and the read-only nature aligns with readOnlyHint annotation. Adds significant context beyond annotations.

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

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

Every sentence is necessary and structured in a logical flow: general purpose, then bullet-like breakdown of parameter combinations. No fluff.

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

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

Thoroughly covers all parameter combinations and edge cases (USD base currency) despite no output schema. The tool's behavior is fully predictable from 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?

While schema covers all parameters (100% coverage), the description adds crucial context on how parameters interact—e.g., what happens when each combination is used—going beyond the schema's individual field descriptions.

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

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

The description clearly states 'Inspect the FX rate cache' and details multiple modes, distinguishing it from sibling tools that deal with other financial data like balances and flows.

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 explains when to use each parameter combination: without currency for coverage, with currency and date for point-in-time lookup, with currency and from/to for series, with currency alone for recent rows. Also clarifies that USD has no rows.

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

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

Annotations already declare `readOnlyHint=true`, and the description reinforces this by calling it a 'snapshot' and 'drill-down', implying no side effects. The description adds value by detailing each return component (indicators, stress index, regime, scenarios), beyond what annotations provide. No contradictions, but lacks mention of performance or rate limits, 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 description is a single, well-structured sentence that efficiently delivers all necessary information: the 8 indicators with sub-details, the index, regime, and scenarios. Every phrase adds value, with no wasted words, achieving high information density while remaining readable.

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

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

Given the tool has only one parameter with complete schema, no output schema, and is a simple read operation, the description fully explains the return structure and references the sibling tool for context. No gaps exist for the agent to invoke 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%, and the schema already describes the parameter with allowed values. The description adds meaning by contextually integrating the parameter ('FX vs the requested display currency') and listing it among the 8 indicators, providing functional significance beyond the schema 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 explicitly states it returns a 'curated macro snapshot' listing 8 specific indicators, Economic Stress Index, regime bias, and scenarios. It distinguishes itself from `get_market_brief` by noting it is 'the same macro + signals block' but a drill-down for when only the macro picture is asked for, providing clear purpose and 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?

The description directly tells when to use this tool: 'call this drill-down when only the macro picture is asked for.' It contrasts with `get_market_brief`, which returns a broader market brief, giving explicit guidance on context of 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 readOnlyHint=true, and the description adds context that monetary values come in display_currency and that numbers match get_market_brief exactly. No contradiction and adds useful behavioral context beyond annotations.

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

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

Two clear sentences, no wasted words. First sentence describes what the tool returns, second explains usage context with sibling differentiation. Well front-loaded.

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

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

Given no output schema, the description adequately describes return contents (holdings table, risk summary) and ties to sibling tool. All necessary context for a single-parameter read-only tool is provided.

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 display_currency with 100% schema coverage. The description explains its role (monetary values in that currency) and lists allowed currencies, adding value beyond the schema's default 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 clearly states it shows 'Current holdings derived from the user's transaction log' and lists specific data fields (ticker, shares, market value, etc.). It distinguishes from sibling get_market_brief by stating it is a drill-down for when only the holdings table is asked for.

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 'for any check-in or what should I do question call get_market_brief first' and 'Use show_portfolio when the holdings table itself is the only thing asked for'. This provides clear when-to-use and when-not-to-use guidance with a named alternative.

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=true, indicating safe read. The description adds valuable context beyond annotations: it lists the exact fields returned (birth year, retirement target year, etc.), specifies that target net worth is in display_currency, and describes the null return when no profile exists. This goes beyond annotation signals.

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 concise with two sentences, no redundant information. The key actions and behaviors are front-loaded, and every word provides value. No filler or unnecessary details.

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

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

Despite having no output schema, the description comprehensively explains what the tool returns (list of fields and their context, null behavior). For a simple read tool with one optional parameter, this is fully complete. No gaps remain.

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

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

The input schema already describes the 'display_currency' parameter with a default and description. The description adds meaning by explaining how the parameter affects the output ('target net worth is returned in display_currency'), which is not explicitly stated in the schema field 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 uses specific verbs ('Read') and identifies the resource ('user's stored profile') with clear enumeration of fields. It inherently distinguishes from sibling tools like 'set_profile' (write) and other 'show_*' tools that access different data (e.g., show_balance, show_portfolio).

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 clearly states the tool's context ('Read the user's stored profile') and explains the null return behavior. While it doesn't explicitly exclude use cases or list when not to use it, the read-only nature is implicit, and no alternative tool is mentioned (though 'set_profile' is a sibling). This is adequate for a straightforward read operation.

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

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

Discloses data sources (Yahoo for benchmark, FRED key for risk-free rate with fallback), default behavior, and the requirement for at least 10 snapshots. Complements the readOnlyHint annotation with additional context.

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 packed with essential information: metrics list, dependencies, defaults, and sibling differentiation. No fluff; every sentence serves a purpose.

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

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

Despite no output schema, the description enumerates all returned metrics. Covers preconditions (10 snapshots), default behavior, and data sources. Leaves no critical information gaps.

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 has 100% coverage with descriptions, but the description adds value by clarifying defaults (e.g., benchmark default SPY, risk_free_rate default Fed funds or 5%) and purpose of each parameter. Does not repeat schema verbatim.

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

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

Clearly states it provides portfolio risk metrics from snapshot history, listing specific metrics (annualized return/volatility, etc.). Distinguishes from sibling 'get_market_brief' by noting it is a drill-down for full breakdown or custom date range.

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 contrasts with get_market_brief, indicating when to use this tool vs that sibling. Also states a prerequisite (at least 10 daily snapshots). Provides clear context for selection.

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

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

Annotations already mark readOnlyHint=true. The description adds behavioral context: dual behavior based on ticker presence, default currency, and a strong warning against misuse for projections. This adds value beyond the annotation.

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

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

Two sentences plus a critical note, no wasted words. Information is front-loaded with the main purpose first, then mode details, then a crucial caveat.

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 4 optional parameters and no output schema, the description explains the two output modes and warns about limitations. It lacks detail on exact response format but is sufficient for a snapshot-history tool.

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

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

Schema coverage is 100% so baseline is 3. The description explains how ticker absence/presence changes output, and notes display_currency defaults to USD, adding context beyond schema descriptions.

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

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

The description clearly states the tool queries portfolio snapshot history and distinguishes two modes: without ticker returns daily total market value, with ticker returns per-day time series. This specificity differentiates it from sibling tools like show_balance or show_portfolio.

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

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

Explicitly states when to use (historical snapshots) and when not to (projections), advising pairing with get_market_brief and project_net_worth. Calls linear extrapolation a 'category error', providing clear exclusionary guidance.

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

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

Annotations already mark readOnlyHint=true. Description adds further behavior details: status meanings (alive/at_risk/broken), immutable ledger_tenure_months, and currency-neutral output. No contradictions.

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

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

The description is detailed but every sentence adds value. Could be slightly shorter, but it's well-structured and informative without redundancy.

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

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

Despite no output schema, the description fully explains all returned fields and their meanings. It's complete for an agent to understand what the tool provides and how to interpret results.

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?

No parameters exist, so schema coverage is 100%. Description adds no parameter info but doesn't need to; baseline 4 is appropriate.

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

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

The description clearly states the tool tracks how consistently the user tends their money, with specific metrics. It distinguishes from siblings like show_balance or show_snapshot by focusing on behavioral habits and streak status.

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 usage guidance: celebrate milestones, nudge settlement when 'at_risk', or answer consistency questions. Also notes currency-neutral nature, helping avoid misuse for monetary queries.

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

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

Annotations already declare readOnlyHint=true, and description reinforces by stating it measures 'short-term market positioning and volatility, NOT intrinsic value'. It adds that it uses Yahoo data (no key required), which is helpful for understanding availability. No contradiction with annotations.

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

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

Three sentences: first lists key indicators, second clarifies intent, third provides usage rules. All information is essential and front-loaded. No filler or redundant text.

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 only 2 parameters and no output schema, the description compensates by detailing the output (indicators, composite scores with labels). It covers data source and use cases, leaving no significant gaps for an AI agent to understand invocation context.

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

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

Schema description coverage is 100% and both parameters (ticker, market) are clearly documented in the schema. The description does not add further parameter details beyond what the schema 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?

The description starts with a clear verb+resource: 'Chart-indicator snapshot for a ticker'. It enumerates specific indicators (RSI, Bollinger Bands, MACD, etc.) and composite scores, making it distinguishable from sibling tools like show_valuation and show_financials that focus on fundamentals.

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

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

Explicitly states it is an 'EXECUTION-ONLY tool' and warns 'Never use the composite scores alone to answer should I buy/sell X?'. Provides clear when-to-use instruction: 'AFTER a buy/sell decision is formed on fundamentals, to size entries, set stop losses, or time exits'. Also mentions data source (Yahoo) and no key required.

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

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

Annotations only provide readOnlyHint, but the description adds significant detail: it lists returned fields (buy price, current price, days held, price change %, held status, outcome label) and mentions coverage_pct. No contradictions.

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

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

The description is concise and well-structured: purpose first, then output fields, use cases, and a practical note about coverage_pct. Every sentence adds value.

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

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

With optional parameters, no output schema, and annotations present, the description covers key output fields and usage context. Missing explicit pagination/ordering details, but 'most recent first' is implied in limit parameter 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 baseline is 3. The description does not add new meaning to parameters beyond what's in the schema, so remains at 3.

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

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

The description clearly states the tool reviews past trades with a recorded reason (thesis) and checks if it played out. It lists specific output fields, distinguishing it from sibling tools like show_portfolio or show_txns.

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

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

Explicit use cases are provided (e.g., 'did my last trade work', 'track record of my AAPL theses'), and guidance on coverage_pct encourages adding reasons. Lacks explicit when-not-to-use, but context is clear.

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?

Adds behavioral details beyond readOnlyHint: ordering by date, filtering logic, price currency. No contradictions.

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

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

Three concise sentences: purpose, filtering, currency. Front-loaded and no fluff.

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

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

Covers what is returned, ordering, filtering, and currency. No output schema, but description is sufficient for a read-only log query.

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 description adds meaning: ticker can be asset name (case-insensitive), display_currency default and role in price.

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

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

Clearly states it provides a full transaction log including buys, sells, deposits, dividends, taxes, ordered by date. Distinguishes from sibling 'show_' tools by being the general log.

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 example usage with ticker filter, mentions case-insensitive matching and price currency. Does not explicitly state when not to use but context is clear.

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

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

Annotations declare readOnlyHint=true, and the description adds valuable context: it explains the dependency on a FRED key for some metrics, the data sources (market fundamentals and FRED series), and the two layers of analysis. This goes beyond the annotation.

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

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

The description is concise, front-loading the main purpose, then listing metrics, usage examples, and data sources. Every sentence adds value without redundancy.

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

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

Given the tool has one parameter, no output schema, and readOnly annotation, the description fully covers expected outputs, data sources, and a key condition (FRED key). It provides a complete mental model for the agent.

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

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

The sole parameter 'ticker' is described in the schema with a clear example ('AAPL'). Schema coverage is 100%, so the description adds no additional parameter semantics. 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 clearly states it performs a valuation deep-dive for a single ticker, listing specific metrics like PEG ratio, Price/Sales, FCF yield, and macro-adjusted spreads. This distinguishes it from sibling show tools by focusing on valuation metrics.

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

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

The description explicitly says 'Use for "is X overvalued / cheap?", "what's the PEG?"', providing clear usage guidance. It does not explicitly mention alternatives or when not to use, but the context is sufficient.

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

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

Description discloses that this is deterministic conditional analysis, point estimate per scenario, not stochastic. Explains defaults for beta (1.0) and daily_vol_pct (null). Annotations already declare readOnlyHint=true, and description reinforces no mutation.

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 length, every sentence serves a purpose: trigger phrases, workflow, examples, exclusions. Front-loaded with purpose, well-structured with bold formatting and bullet-like workflow.

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 4 parameters, nested objects, and no output schema, description fully explains input construction, defaults, and output nature (point estimate per scenario). Also references sibling tool get_market_brief for prerequisite data.

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 description adds significant value beyond the schema: explains how to construct scenarios (bear/base/bull), how to pull data from get_market_brief, and the meaning of each parameter in context.

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

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

Description clearly states the tool is for short-horizon scenario analysis, provides trigger phrases, and distinguishes from project_net_worth (long-horizon stochastic). Verb 'simulate' with specific resource 'scenario'.

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 lists when to use (short-horizon, specific trigger phrases), when not to use (long-horizon, use project_net_worth), and provides a step-by-step workflow. Also states what caller must supply (shocks) and disclose.

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?

Description implies a mutation (starting a trial, changing account state), but annotations have readOnlyHint: true. This is a clear contradiction: readOnlyHint means no changes, while the description describes a state change.

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 that front-load the main action and cover when to use and restrictions, with no unnecessary words.

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

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

The description adequately explains the purpose, condition, and restrictions for the trial tool. However, the contradiction with annotations detracts from completeness, as the agent may be misled about the tool's side effects.

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?

No parameters exist, so the description cannot add meaning beyond the schema. Baseline for zero parameters is 4, and the description does not need to compensate.

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

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

The description clearly states the tool starts a one-time free 60-day trial of Opula Pro, specifying the condition for offering it (when upgrade_required with trial_available:true). This distinguishes it from sibling tools that deal with balances, transactions, etc.

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 offer the trial (when a Pro tool returns upgrade_required with trial_available:true) and states it is one trial per account, cannot be restarted, and not for accounts already on Pro. Provides clear usage context and exclusions.

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 indicate non-destructive, non-read-only. Description adds 'increment-only' behavior and mentions it fetches from FRED, but doesn't detail side effects or rate limits. Adequate for simple tool.

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 with front-loaded action and currencies. Each sentence adds value, no 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?

Given zero parameters and no output schema, the description fully covers purpose, currencies, and usage context. Complete and self-contained.

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?

No parameters, so schema covers fully. Description adds no param information, but baseline 4 applies per scoring guide.

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

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

The description clearly states the tool backfills the historical FX rate cache from FRED, naming specific currencies. It distinguishes from siblings like show_fx by indicating this is for backfilling, not displaying, rates.

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

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

Explicitly states necessity for converting non-USD entries and that entry tools handle today-dated entries automatically, so manual use is rarely needed.

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