firma

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

With no annotations, the description fully discloses behavior: upsert semantics (overwrite on same composite key), currency conversion, and return values for single vs multi-entry calls. 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 relatively long but every sentence serves a purpose. It is front-loaded with the core action and then provides necessary details. Minor redundancy could be trimmed, but overall well-structured.

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

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

Given the complexity of the tool (upsert, multi-entry, currency conversion) and no output schema, the description covers all necessary aspects: categories, sub_types, currency handling, return values, and appropriate sibling tool reference. It is fully 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: explains array usage patterns, valid category strings, sub_type mapping, currency conversion details, and return value behavior. This significantly aids correct 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?

The description clearly states 'Upsert one or more balance sheet entries (also edits — same composite key overwrites)' and distinguishes from sibling 'add_monthly' by advising to prefer that for full month-end settlement. The verb and resource are specific.

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 this tool vs alternatives: 'Prefer add_monthly for full month-end settlement.' Also provides detailed instructions on category, sub_type, and currency usage, guiding correct invocation.

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?

Given no annotations, the description discloses that it performs upserts (overwrites on same key), describes single vs multi-entry return behavior, but does not cover authorization or rate limits.

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

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

The description is front-loaded with the core purpose and usage, but the long list of categories, while necessary, adds length. Still efficient overall.

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 covers return behavior (single vs multi-entry), upsert semantics, and category constraints, making it complete for the tool's 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?

Schema coverage is 100%, but the description adds significant value by explaining that entries can be one or many for spreadsheet-like import, listing valid categories, and describing return values.

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

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

The description clearly states the tool upserts cash flow entries and mentions that the same composite key overwrites, which distinguishes it from siblings like add_balance and add_monthly.

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 advises to prefer add_monthly for full month-end settlement and warns to use only predefined categories, providing clear alternative and constraint.

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?

No annotations are provided, so the description carries full burden. It explains the batch 'upsert' behavior for a single period, which implies creation/update, but doesn't disclose whether it replaces or appends existing period data, or mention authorization or rate limits. Some transparency but gaps remain.

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

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

The description is front-loaded with the core purpose and includes necessary detail on valid categories and workflow. While lengthy, every sentence serves a purpose for correct tool invocation. Could be slightly more concise but remains efficient.

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 2 required and 2 optional parameters with no output schema, the description covers the main use case, data constraints, and post-call action (call report). It lacks error handling or behavior on duplicate periods, but is sufficiently complete for the intended monthly settlement task.

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 adds significant value by listing all valid category strings and their required sub_type (e.g., 'assets: cash, savings, ...'). This compensates for the schema's free-text sub_type and category fields, ensuring correct parameter usage beyond schema definitions.

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

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

The description clearly states 'Batch upsert balance and flow entries for a single period in one call', specifying the verb (batch upsert) and resource (balance and flow entries). It distinguishes from siblings by highlighting it as the primary tool for month-end settlement, unlike individual add_balance/add_flow tools.

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

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

Provides explicit step-by-step instructions for when to use: 'When the user says "결산", "월말 결산", "month-end closing", or "record this month"' and outlines the required workflow (ask for categories, confirm numbers, call tool once). It also lists valid categories and sub_types, preventing misuse.

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

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

With no annotations, description carries full burden. It discloses behavior: resolves name case-insensitively, converts currency to USD at today's date, returns error for stocks and unknown names. 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?

Very concise yet comprehensive. Front-loaded with purpose, then details. No redundant sentences. 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?

Given no output schema and no annotations, description covers purpose, usage, parameters, behavior, and error cases. Complete for a simple mutation 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. Description adds context: explains asset types, currency conversion, and stock restriction, which adds value beyond schema fields.

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

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

Description clearly states 'Set the current price of ONE non-stock asset' and lists categories. It distinguishes from stocks, which are auto-priced by sync. Purpose is 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?

Explicitly states when to use: for non-stock assets without market data. Provides clear exclusion: not for stocks (use sync instead). Also describes error handling for unknown names and stock attempts.

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?

Without annotations, the description discloses external dependency (Finnhub) and the two-step process (sync then record). But it does not clarify idempotency, side effects on existing prices, or error conditions.

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 sentence with two clear clauses, no redundancy, and front-loads the key action and prerequisite.

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, no output schema, and no annotations, the description adequately explains purpose and precondition. It could mention return value or error handling, but it is still fairly complete for a simple creation 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?

With zero parameters, the description adds meaningful context by explaining that the tool uses today's date implicitly and involves syncing external prices, which goes beyond the empty 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 syncs latest prices from Finnhub and records a snapshot for today, which distinguishes it from sibling tools like add_balance, edit_snapshot, or show_snapshot.

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

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

The description explicitly says it is 'required before snapshot data is useful', providing clear context for when to use it. However, it does not mention alternatives or when not to use it.

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

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

No annotations are provided, so the description fully bears the transparency burden. It discloses critical behaviors: rows sorted by date ascending, price conversion to USD, asset-type-specific handling (stock vs non-stock), ignoring currency for stocks, and the different return formats for single vs multi-entry calls. This is comprehensive and leaves little ambiguity.

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 relatively long but well-organized, with clear sections and front-loaded core action. Every sentence adds value given the tool's complexity. It could be slightly more concise, but the structured presentation (type-specific details, reason capture guidelines) justifies the length. Score 4 for being slightly verbose but highly efficient in content.

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

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

Given the tool's complexity (multiple transaction types, asset classes, markets, currencies) and absence of an output schema, the description is remarkably complete. It covers the full behavioral model: asset-type flow splits, currency conversion rules, reason capture protocols, and return format. No notable gaps remain for an agent to infer.

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

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

While the input schema already has 100% coverage of parameters, the description enriches meaning far beyond the schema descriptions. For example, it explains the semantic difference between 'buy/sell' and 'deposit/dividend/tax', clarifies the interplay between 'market' and 'currency', and provides detailed guidance on the 'reason' parameter's importance for thesis tracking. This significantly aids correct parameter 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?

The description clearly states 'Insert one or more transactions in a single call', specifying the verb (insert) and resource (transactions). It goes beyond a simple statement by explaining the array structure and common use cases (single trade vs bulk import), effectively distinguishing this tool from sibling tools like delete_txn or edit_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?

The description provides explicit when-to-use and when-to-avoid guidance. It details the bulk import workflow (show mapping, wait for confirmation), and specifies when to ask for the 'reason' field (new buy/sell trades) versus skip (historical data or non-buy/sell types). This level of procedural instruction is exemplary.

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?

No annotations are provided, so the description must fully disclose behavior. It covers the conditional deletion logic but lacks details on side effects, permissions required, reversibility, or return value. The behavioral context is incomplete.

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 two sentences, efficiently conveying the core purpose and conditional logic with no extraneous words. It is 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?

Given the tool has 4 parameters, conditional behavior, and no output schema, the description is adequate but minimal. It lacks details on return format, prerequisites (e.g., period must exist), or risk warnings for bulk deletion. Not fully 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 the schema already describes each parameter. The description adds little new meaning beyond restating the conditional behavior for category. It does not enhance understanding significantly.

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 verb 'delete' and resource 'balance entries', and distinguishes between single-entry deletion (with category) and bulk deletion (all entries for the period). This differentiates it from sibling tools like 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?

The description implies when to use (delete balance entries) and gives conditional behavior, but does not explicitly state when not to use or provide alternative tools for other record types. The agent must infer usage from 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that deletion is conditional on category, but fails to mention whether the operation is irreversible, requires special permissions, or has any side effects (e.g., cascading deletes). This is insufficient for a potentially destructive action.

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, no redundancy, and the conditional logic is front-loaded. Every word earns its place.

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

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

Given the absence of annotations and output schema, the description is too minimal. It omits critical details for a mutation tool, such as whether the operation is reversible, what happens to related records, and expected return values. The schema covers parameter meanings but not behavioral 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 the parameter descriptions already explain the conditional behavior (e.g., category: 'Specific category — if omitted, deletes all entries for the period'). The description adds no new semantic meaning beyond what the schema provides, 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 states the verb ('delete'), resource ('flow entries'), and scope ('for a period'), with conditional logic for category. It effectively distinguishes from sibling tools like delete_balance, delete_snapshot, and delete_txn by specifying the resource type and conditional behavior.

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

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

The description implies usage for deleting flow entries by period or specific category, but provides no explicit guidance on when to choose this tool over other delete tools or any alternatives. There are no usage conditions or exclusions stated beyond the conditional logic.

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 the destructive nature of the operation ('Delete all portfolio snapshot rows'). With no annotations provided, the description carries the full burden, and it does so adequately, though it could mention irreversibility or confirmation needed.

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: first gives action and format, second gives usage guidance. Every sentence is necessary and front-loaded with critical 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?

For a simple one-parameter tool with no output schema or annotations, the description is fairly complete. It covers the action, parameter format, and usage context. Some may want confirmation details, but overall it's sufficient.

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

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

Schema coverage is 100% and the description repeats the date format already present in the schema. It adds no new semantic meaning beyond the schema, so 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 the specific action (delete), resource (portfolio snapshot rows), and condition (for a given date in YYYY-MM-DD format). It distinguishes itself from sibling tools like add_snapshot and show_snapshot.

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

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

Explicitly says 'Use only when the user explicitly asks to remove a bad snapshot — destructive,' providing clear when-to-use and warning of destructiveness. This is high-quality 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?

With no annotations, the description reveals that deletion recalculates positions and average cost—an important side effect. It also notes the need for explicit user confirmation. Not fully detailed (e.g., reversibility, permissions), but adequate for a simple delete 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?

Three sentences, all relevant: purpose, usage guideline, and behavioral effect. No redundancy, front-loaded with the action. 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?

Given one parameter and no output schema, the description covers the essential aspects: purpose, confirmation requirement, and side effect. Could mention constraints or error cases, but the current information is sufficient for an 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?

Schema coverage is 0%, so the description must compensate. It only says 'by its id,' which adds minimal meaning beyond the schema's 'id' field. No details on valid ID values or formats beyond what the schema provides.

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 'Delete a single transaction by its id,' which uses a specific verb and resource. It clearly distinguishes from sibling delete tools (e.g., delete_balance, delete_flow, delete_snapshot) by naming 'transaction.'

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. This provides strong when-to-use guidance. Lacks explicit alternatives or when-not-to-use scenarios, but the warning is clear and 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?

No annotations are provided, so the description carries the burden. It reveals that market is ignored for non-stock assets, but does not disclose error behavior (e.g., if snapshot does not exist), whether updates are partial or full replacements, or any authorization needs. This is adequate but not comprehensive.

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 two sentences, concise and well-structured. Every sentence adds value without redundancy, making it 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?

Given 7 parameters and no output schema, the description covers identification and field updates but omits important context such as the requirement for an existing snapshot (presumably created via add_snapshot) or idempotency behavior. It is adequate for basic use but leaves gaps 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 57%, and the description adds value beyond schema by clarifying identification logic (date + asset_type + market + ticker) and the market handling for non-stock assets. It compensates for missing schema descriptions and provides business 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?

The description clearly states that the tool updates shares, avg_price, or current_price for a holding in a snapshot, identified by date and asset details. It distinguishes from siblings like edit_txn by focusing on snapshot holdings, and explains special handling for non-stock assets.

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

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

The description implicitly indicates when to use (updating snapshot holdings) but does not explicitly mention when not to use or provide alternative tools. It gives context for non-stock assets, which is helpful, but lacks direct guidance on exclusion 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?

No annotations provided, so description carries full burden. It discloses price conversion rules (to USD, dependent on asset type and market) and asset_type change side effects (clearing market). Missing details on idempotency, error handling, and return value.

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

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

Three well-organized sentences: purpose, price behavior, asset_type behavior. No wasted words, but could be more concise by removing redundancy (e.g., 'only provided fields' repeated).

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 core update semantics and key behavioral traits. However, lacks return value information (no output schema), error conditions, and additional constraints for other parameters like date format validation or ticker requirements. Adequate for moderately complex tool but not fully comprehensive.

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 60%. Description adds significant detail for 'price' (conversion logic) and 'asset_type' (clearing behavior). For other params (date, type, shares, etc.), it relies on schema descriptions, which are adequate but not enhanced. Overall adds meaningful value 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?

Clear verb 'update' and resource 'transaction' with scoping 'by id' and 'only provided fields changed'. Distinguishes from create/delete siblings.

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

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

Implies usage for modifying existing transactions but lacks explicit when-to-use, when-not, or alternative tool references. Sibling context hints at create/delete, but no direct 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?

No annotations exist, but the description thoroughly covers behavioral traits: it is deterministic (no forward-looking probabilities), cached per day, and returns a composite snapshot. It does not mention side effects, but none are expected for a read operation. The description compensates well for the lack of 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 (about 150 words) but well-structured: purpose first, then usage, then deterministic nature, currency details, comprehensive list of return bundles, sibling differentiation, and caching. Every sentence adds value, though slightly more conciseness could be achieved.

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 and two optional parameters, the description provides a full picture: what the tool does, when to use it, what it returns (detailed bundle list), its deterministic and cached behavior, and how it relates to sibling tools. It is comprehensive for a complex diagnostic 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?

Both parameters are documented in the schema (100% coverage), and the description adds value by explaining display_currency's role ('USD = no FX line') and listing allowed currencies. It also clarifies refresh as 'force regenerate, bypass today's cache'. This enriches the schema definitions.

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

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

The description clearly states it is a 'composite read of *current* portfolio state' and differentiates from siblings like project_net_worth (probabilistic projections) and show_* tools (drill-downs). It uses a specific verb (read) and resource (current portfolio state), making the purpose unmistakable.

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 advises 'Call this FIRST' and explains that it obviates multiple tool calls for common questions. It provides direct alternatives: use project_net_worth for probabilistic projections and show_* tools only for detail when needed. This is exemplary usage 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?

No annotations provided, so description carries full burden. Discloses: monthly GBM, cross-scenario shared seed, target_value behavior, horizon range, iteration precision, path resolution impact. Covers most behavioral aspects, but could be more explicit about probabilistic nature of output.

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

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

Description is long but each sentence adds value, front-loaded with core purpose. Could be slightly more concise by grouping related concepts, but overall efficient given 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?

Despite no output schema, description fully explains output (percentiles, probability, median months), simulation process, and all parameter options. Covers how to obtain historical reference via brief.risk_summary. Complete for a complex tool with 11 parameters.

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 3. Description adds value by explaining how horizon_months covers short/long horizons, target_value changes response, scenarios share same seed, and iteration defaults affect precision. Provides context beyond 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 explicitly states 'forward-looking Monte Carlo projection of net worth under caller-supplied assumptions, multi-scenario', clearly defining the resource (net worth projection), method (Monte Carlo), and scope. It distinguishes from sibling 'get_market_brief' by positioning this as the thought-experiment tool vs. a diagnostic tool.

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

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

Provides clear guidance: use get_market_brief for current portfolio state, this tool for projections. Explains how to set scenarios (must set return/vol explicitly, disclose to user), and references brief.risk_summary for a historical scenario. Does not explicitly state when not to use, but covers when to use and alternatives well.

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?

No annotations exist, so the description carries full burden. It describes the outputs of each view (monthly trends, income/expenses, single-period summary) without revealing side effects or auth needs. Implies read-only behavior but does not explicitly state it; lacks explicit idempotency guarantee.

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

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

The description is dense but well-organized, using bold and backticks for clarity. It front-loads the core purpose and maps targets to outputs. Minor redundancy could be trimmed, but remains efficient.

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

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

No output schema exists, so the description must cover return values. It describes outputs for each view and explains the relationship to sibling tools. Lacks structural details (e.g., data types), but is sufficient for a reporting tool given 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 coverage is 100%, baseline is 3. The description adds value for 'target' by detailing each enum value and for 'period' by noting default behavior. For 'currency' and 'limit', it provides minimal extra context beyond the schema, but overall compensates adequately.

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 produces aggregated wealth reports and lists four distinct views (balance, flow, settle, combined) with specific use cases. It also differentiates from sibling tool show_snapshot by noting when to pair them.

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 identifies it as the primary entry point for wealth-trajectory questions and explains why portfolio value alone is insufficient. Provides guidance on when to pair with show_snapshot, offering clear when-to-use and when-not-to-use 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?

Details partial update behavior, field constraints (4-digit years, currency conversion to USD, enum values), and free-form notes. No annotations are present, so the description carries the burden; it adequately discloses key behaviors 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?

Two sentences: first states purpose and partial update, second lists field constraints. Every sentence adds value; no fluff. Front-loaded with 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?

For a simple update tool with 6 optional parameters and no output schema, the description covers the essential behavior, field formatting, and currency conversion. No critical 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?

Adds significant meaning beyond the schema: explains 4-digit years for birth_year and retirement_target_year, currency conversion for target_net_worth, enum values for risk_tolerance, and free-form for notes. Schema coverage is only 33%, 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?

The description starts with 'Update the user's profile,' clearly stating the verb and resource. It specifies partial updates, distinguishing it from sibling tools like 'show_profile' (read) and others.

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 'Partial updates — only provided fields are changed' and 'All fields are optional; capture only what the user volunteers, never invent values.' Provides clear context but does not explicitly mention when not to use or alternative tools.

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

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

With no annotations, the description fully covers what the tool returns: API key state, data counts, profile, next steps, capabilities, and analyst_context. It also explains how to treat capabilities as a hard gate, preventing fabrication.

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 yet comprehensive single paragraph. Front-loaded with purpose and usage, followed by return values and critical instructions. No 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?

Given zero parameters and no output schema, the description provides all necessary context: purpose, when to call, what it returns, and how to interpret results. Complete for the tool's role.

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 baseline is 4. The description adds value by detailing the return fields, which compensates for missing output 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?

Clearly identifies as a one-shot setup diagnostic tool. Distinguishes from sibling tools like add_balance or show_txns which operate on specific data, while this tool checks data availability and capabilities.

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 at the start of every conversation and any time unsure of data availability. Provides clear context for use without needing 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?

Despite no annotations, description thoroughly explains output and implied read-only nature. Could explicitly state no side effects, but is adequate.

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?

Description is informative but slightly verbose; still well-structured with purpose first, then details and usage guidance.

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 output schema, description fully explains return values, including label conditions. Also covers usage context and pairing, making it 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% and both parameters have clear descriptions. Description adds no extra meaning beyond the schema, so 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?

Clearly states the tool tracks post-exit performance of fully sold positions, with specific metrics and labels. Differentiates from peers like show_thesis_track and 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: when contemplating a sell, reviewing past decisions, or asking about sell outcomes. Also suggests pairing with show_thesis_track.

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?

Describes return structure (type, sub_type, category, amount, date) and behavior with period. However, no annotations exist, and the description does not explicitly state this is a read-only operation, though implied by 'show'.

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

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

Three sentences, each serving a purpose: purpose, structure, and usage guidance. No wasted words, front-loaded with key information.

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

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

Covers purpose, parameters, return structure, and usage modes. Lacks explicit read-only declaration and pagination details, but sufficient for a simple listing tool given 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 the description adds value by explaining the optionality of 'period' (all vs. snapshot) and listing currencies for 'display_currency' beyond the schema's short 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?

Clearly states the tool retrieves balance sheet entries (assets + liabilities) by period. Distinguishes itself from sibling 'show_' tools by specifying the data type (balance sheet) and behavior with/without period.

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 without period (trends) and with period (snapshot). Does not mention exclusions or alternatives, but the guidance is clear for common 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?

Given no annotations, the description discloses two distinct behaviors: using daily snapshot history when available, otherwise falling back to cost-basis vs current value. This provides useful transparency about data dependencies, though it could mention output format or potential limitations.

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 cover purpose, default benchmarks, and fallback behavior. Every word is necessary; no fluff. Efficient and well-structured.

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 explains the tool's mechanism but does not describe the output format or what the agent can expect as a result. Since no output schema exists, the description should fill that gap, which it does not.

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 adds no new parameter-level meaning beyond what the schema already provides (defaults are stated in schema). The fallback behavior is tool-level context, not parameter-specific.

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 compares portfolio return against benchmark indices, specifying default benchmarks (SPY and QQQ). It effectively distinguishes from sibling tools like show_portfolio or show_risk by focusing on benchmark comparison.

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

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

The description explains how the tool operates (snapshot-based or fallback) but does not explicitly state when to use it over alternatives or when not to use it. The purpose is clear, but guidance on context is lacking.

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

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

With no annotations provided, the description fully bears the burden. It explains HHI range and thresholds, the dependency on sync for correlation data, and the interpretation of effective-N, providing thorough 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 a single paragraph of four sentences, well-structured and front-loaded with the main purpose. Slightly verbose in places but overall efficient.

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

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

Even without an output schema, the description comprehensively details all return components (HHI per dimension, top contributors, correlation matrix, effective-N) and their interpretation, making it fully complete 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?

No parameters exist; schema coverage is 100% (empty). The description adds value by clarifying what the tool returns, even without inputs, so baseline 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 precisely states it measures portfolio concentration via HHI across ticker, currency, sector, and country dimensions, clearly distinguishing it from sibling tools like show_portfolio or 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?

It notes that effective_n/correlation_matrix require a prior 'firma sync' to be populated, giving implicit usage context. However, it does not explicitly compare to alternatives or state 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?

With no annotations provided, the description carries full burden. It discloses that values are estimated and that only tickers with dividend data are included, which is good transparency. However, it does not explicitly state that it is a read-only operation, though that is implied.

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: one stating the main purpose and output, and another providing scope limitation. Every word adds value, and it is front-loaded with the primary function.

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

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

Given the simple one-parameter input and no output schema, the description is fairly complete. It explains what is returned, the currency handling, and the limitation to tickers with data. It could mention the calculation basis for yield, but overall adequate.

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 a clear description of the display_currency parameter. The description reinforces the default and usage in context, but adds no significant new meaning beyond what the schema already provides.

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 reports estimated annual dividend income for all holdings, including per-ticker yield, annual DPS, and estimated income in a specified currency. It distinguishes from sibling tools like show_earnings by focusing specifically on dividend data.

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

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

The description implies usage for retrieving dividend information, but lacks explicit guidance on when not to use or how it compares to alternatives. The sibling tools list is extensive, but the description does not directly address when to choose this tool over others.

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

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

The description discloses the dual behavior (with/without ticker) but lacks details on authentication needs, rate limits, data freshness, or error handling. Since no annotations are provided, the description carries full burden; it is adequate but not thorough.

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 two sentences, front-loaded with the action, and contains no unnecessary words 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?

For a simple earnings calendar tool with no output schema, the description covers the main usage modes. It could be improved by hinting at return format or error cases, but overall it is sufficient for the complexity level.

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

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

Schema description coverage is 100%, so the input schema already documents all three parameters. The description adds no additional parameter information beyond the schema. Per guidelines, 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 fetches earnings calendar and distinguishes two modes: without ticker for upcoming earnings for all held tickers, and with ticker for history plus upcoming. This differentiates it from sibling tools like show_financials or show_valuation.

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 implicitly guides usage by describing the two modes (omit ticker for portfolio overview, include ticker for specific company data). It does not explicitly state when not to use or mention alternatives, but the context is clear enough.

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?

No annotations exist, and the description does not disclose behavioral traits such as data freshness, rate limits, permissions, or limitations. The extraction from XBRL filings is mentioned but without implications for availability.

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 two sentences with no redundancy. The first sentence states purpose, the second lists output components. Every word 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?

Without an output schema, the description should detail return values more. It mentions 'key metrics' from three statements but does not specify which metrics. Parameter context is not enhanced. Adequate but incomplete.

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 67% (ticker and limit have descriptions, freq only has enum). The tool description adds no additional meaning beyond the schema, so it meets the baseline but does not compensate for the missing freq 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 the tool fetches SEC-reported financials for a ticker, specifying the resource (financial statements) and what is returned. However, it does not explicitly distinguish it from sibling tools like show_balance or show_earnings, which may overlap.

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

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

No guidance is provided on when to use this tool versus alternatives or any prerequisites (e.g., US companies only). The description implies general usage but lacks explicit 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?

With no annotations, the description implies read-only behavior by saying 'stored entries' but does not explicitly state side effects, auth needs, or rate limits.

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 purpose and cover parameter behavior and alternative, with no 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?

Describes return entry structure and parameter effects. No output schema but description covers what to expect. Could mention pagination or response format but not required.

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 description adds minimal value beyond schema. It reiterates period format and display_currency default already in 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 retrieves stored monthly cash flow entries with fields and explains behavior with/without period, distinguishing it from sibling tools.

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

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

The description explains when to use without period vs with period, and suggests an alternative (report with target 'flow') for trend analysis, but does not explicitly state 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?

With no annotations, the description fully discloses behavior: caching, fallback using lookback_days, and the special case for USD. It outlines return types for each invocation mode, making the tool's behavior transparent.

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?

Description is concise (5 sentences) and front-loads the core purpose. Each sentence adds distinct information about a different invocation pattern, with 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?

Despite no output schema, the description fully explains return values for all parameter combinations, covers edge cases (USD, fallback), and addresses all six parameters. It is complete for the tool's 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?

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining combinatorial logic (e.g., 'with currency + from/to returns series'), which is beyond the individual parameter descriptions in the schema.

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

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

Description states specific verb ('Inspect') and resource ('local FX rate cache'), and clearly explains the base unit (USD). It distinguishes from sibling tools by focusing on FX rates, which is unique among the many '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?

Description provides clear context for different parameter combinations and their outputs. It does not explicitly compare to sibling tools or state when not to use this tool, but the specificity of the tool makes its usage context obvious.

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?

Without annotations, the description discloses all output components (8 indicators, stress index, regime bias) and the effect of display_currency. It lacks mention of idempotency or rate limits but is otherwise transparent.

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 efficiently convey full scope with front-loaded overview, 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?

Given no output schema, the description fully explains the three output sections (indicators, stress index, regime bias) with enough detail for an agent to know what to expect.

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

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

Schema coverage is 100%, and the description adds concrete meaning: 'display_currency arg drives the FX series selection (USD = no FX line)', which is not in 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 clearly states it provides a 'curated macro snapshot' with specific indicators, stress index, and regime bias. It distinguishes from siblings like get_market_brief by detailing exact contents.

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 macro overview but does not explicitly state when to use versus alternatives like get_market_brief, nor provides 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?

No annotations available, but description discloses defaults (7 days, limit 10), output structure, and data source (Finnhub). Could mention idempotency or lack of side effects, but overall clear.

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 no wasted words. Front-loads purpose, then provides usage guidance efficiently.

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

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

For a simple read tool without output schema, description covers purpose, parameters, behavior, and alternative. No gaps given tool 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?

Schema covers all 3 parameters with descriptions (100% coverage). Description adds context about 'cap' and defaults but doesn't significantly extend 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?

Clearly states 'Recent company news from Finnhub for a single ticker' with specific output fields (headline, summary, source, timestamp, URL). Distinguishes from sibling get_market_brief which aggregates across holdings.

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

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

Explicitly tells when to use and when not: 'For news across all holdings in one call, prefer get_market_brief which aggregates the last 24h.' Also provides default lookback and limit 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?

No annotations provided, but the description compensates fully: it explains return fields, currency handling, asset_type values, syncedAt semantics, edge cases (null syncedAt/currentPrice), and optional risk summary. All behavioral traits are disclosed.

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 well-structured, front-loaded with purpose and key fields. While it could be slightly more concise, every sentence adds value and the flow is logical.

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

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

With no output schema, the description fully covers return fields, edge cases, and usage context. It leaves no critical gaps for an agent to understand what the tool does and returns.

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). The description adds extra context: lists allowed currency codes and explains FX decomposition behavior when non-USD, enhancing meaning beyond the schema's brief 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 returns 'Current holdings derived from the user's transaction log' and lists specific fields (ticker, shares, avg cost, etc.). It also distinguishes itself from siblings by positioning itself as a drill-down tool and recommending get_market_brief for broader queries.

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 this tool ('when the holdings table itself is the sole thing asked for, or to inspect FX decomposition') and when not to ('call get_market_brief first'). Names a clear alternative (get_market_brief) that provides broader 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?

No annotations provided, so description carries full burden. Describes read-only behavior, return format (fields and null case), and default 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?

Two sentences: first states purpose and fields, second gives usage guidance. Front-loaded, 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?

Covers what is returned, null case, currency default, and usage context. No output schema needed for this simple 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?

Single parameter (display_currency) with 100% schema coverage. Description adds context that target net worth is returned in display_currency (default USD), reinforcing schema 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?

Clearly states 'Read the user's stored profile' and lists specific fields (birth year, retirement target, etc.). Differentiates from sibling tools like set_profile and 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?

Explicitly says 'Use this to anchor analysis to the user's actual goals rather than generic advice,' providing clear context. Lacks explicit 'when not to use' but sufficient for most agents.

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

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

With no annotations provided, the description carries full burden for behavioral transparency. It discloses that the tool derives metrics from snapshot history and requires a minimum data count, but it does not mention idempotency, side effects, or return format. The disclosure is adequate but not comprehensive.

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 two sentences with no fluff. It front-loads the tool's purpose and output in the first sentence, and provides a critical prerequisite and actionable advice in the second. Every phrase 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?

The tool computes multiple risk metrics but lacks an output schema, so the description should clarify the return format. It lists metrics but does not specify if they are returned as an object, array, or single value. For a tool with no output schema and moderate complexity, the description is partly complete but missing structural details.

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

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

Schema coverage is 100% with each parameter already described (e.g., 'Start date YYYY-MM-DD'). The description does not add additional meaning or usage tips 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 states the tool computes portfolio risk metrics from snapshot history, listing specific metrics (annualized volatility, Sharpe, etc.). It distinguishes itself from sibling 'show_' tools by focusing on risk metrics and requiring snapshot data.

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

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

The description explicitly states a prerequisite of at least 10 daily snapshots and suggests an alternative action (running 'firma add snapshot') if the user lacks sufficient data. This provides clear guidance on when and how to use the tool, though it doesn't explicitly compare to alternative sibling tools.

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

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

With no annotations, the description fully explains the behavioral distinction between with/without ticker, and warns about the tool's limitation for projections. It does not mention authentication or rate limits, but covers the key behavioral traits for correct usage.

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

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

The description is front-loaded with the core purpose and efficiently adds contextual warnings. It is slightly long but every sentence contributes meaning, maintaining a good structure for quick scanning.

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

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

Given no output schema and moderate complexity, the description covers parameter effects, currency, and the critical caveat about projection questions, while also referencing complementary tools. It lacks return format details but is sufficient for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the semantic difference between ticker present/absent, and mentions the default and effect of display_currency, going beyond the schema's 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 it queries portfolio snapshot history, with a specific distinction between aggregate (without ticker) and per-holding (with ticker) data. This specificity and contrast with the sibling tool set effectively communicates the tool's purpose.

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

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

The description explicitly advises when not to rely solely on this tool, especially for forward-looking questions, and names specific alternatives (get_market_brief, risk_summary). This provides exceptional guidance on when to use and when to avoid.

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?

No annotations are provided, but the description clearly indicates this is a read-only review tool by using verbs like 'review' and 'returns'. It describes the output fields in detail, including outcome labels and coverage_pct, which helps the agent understand what to expect. However, it doesn't explicitly state that no data is modified.

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 that front-loads the main purpose and includes important usage details. It is concise but covers all necessary aspects, though it could be slightly shorter by combining sentences.

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

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

Despite having no output schema, the description thoroughly explains the return fields (buy price, current price, days held, price change %, still held, outcome label, coverage_pct). It also provides usage context and guidance on encouraging user to add reasons, making it complete for the tool's 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?

All three parameters (ticker, limit, display_currency) have descriptions in the input schema, achieving 100% coverage. The description adds context about portfolio-wide review when ticker is omitted and mentions coverage_pct in output, but doesn't add significant meaning beyond the schema for the parameters themselves.

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 specific action ('Review past trades that have a recorded reason') and resource (thesis trades), clearly distinguishing from sibling tools like show_portfolio or show_txns. It explicitly states the tool evaluates theses, which is unique among the listed siblings.

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

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

The description provides explicit usage examples ('did my last trade work', 'what's the track record of my AAPL theses') and guidance on when to use it (reasoning about a new buy). It also gives advice on interpreting coverage_pct, helping the agent decide when to prompt the user.

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

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

With no annotations, the description takes on full disclosure responsibility. It explains the ascending date order, case-insensitive ticker filtering for both stocks and non-stocks, and the currency handling (original currency per row, price in display_currency). These are useful behavioral traits, though pagination or row limits are not addressed.

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 (four sentences), front-loaded with the core purpose, and each sentence adds new information without repetition. It is well-structured and efficient for an AI agent to quickly grasp the tool's function and usage.

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?

Although the description covers the main transaction types, ordering, and currency behavior, it lacks details about the full set of output fields (e.g., date, quantity, transaction type) since there is no output schema. For a log tool, listing typical columns would improve completeness, but the given info is minimally adequate.

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). The description adds value beyond the schema: it clarifies that ticker filter works for non-stock assets and is case-insensitive, and it explains how display_currency affects the returned price. This enriches parameter understanding beyond the schema's basic text.

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

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

The description clearly states it returns a 'Full transaction log (buys, sells, deposits, dividends, taxes) ordered by date ascending.' This specific verb-resource combination with transaction types and ordering makes the purpose unmistakable, and it distinguishes itself from sibling 'show_*' tools by focusing on individual transaction records.

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 per-transaction queries like 'show me all my AAPL trades' but does not explicitly state when to prefer this over sibling tools like show_portfolio (aggregated holdings) or show_balance. No exclusions or alternative tool names are mentioned, leaving the agent to infer the 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?

No annotations are provided, so the description carries full burden. It discloses data sources (price cache for market cap/PE, XBRL filings for other data) and a prerequisite (Finnhub key). It doesn't specify error behavior, but the transparency is high for a 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?

The description is three sentences with no wasted words. The first sentence lists the output metrics, the second gives usage triggers, and the third mentions data sources and prerequisites. It is front-loaded and efficient.

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 no annotations, the description adequately covers purpose, usage, data sources, and a prerequisite. It could be more complete by noting possible errors or return format, but it's sufficient for its simplicity.

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% (only one parameter with description). The description adds value by explaining that the ticker parameter is used to fetch data from multiple sources, going beyond the schema's simple 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 performs a 'valuation deep-dive for a single ticker' and lists specific metrics (PEG ratio, Price/Sales, FCF yield). It distinguishes itself from sibling tools like show_earnings and show_financials by focusing on valuation.

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 provides usage examples: 'Use when the user asks is X overvalued / cheap?, what's the PEG?, how does the valuation look?'. This directly guides an AI agent on when to invoke the tool.

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

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

No annotations are provided, so the description fully bears the burden. It transparently explains the deterministic conditional analysis approach, how beta_overrides and daily_vol_pct affect results, and what defaults occur (beta=1.0, one_sigma_range null). This gives a clear mental model of the tool's behavior.

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

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

The description is thorough but slightly lengthy. However, it is well-structured with bold key terms, workflow steps, and examples. Every sentence serves a purpose, earning its place. Minor shortening could be possible without losing clarity.

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 (4 parameters, nested objects) and the absence of an output schema, the description provides complete context: workflow, sourcing parameters, constructing scenarios, and distinguishing from sibling tools. No gaps remain for an AI agent to infer.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema: it explains how to structure scenarios (bear/base/bull, conditional pairs), how beta_overrides are sourced from `get_market_brief`, and the conventional patterns. This greatly aids correct 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?

The description precisely states the tool's purpose: answering short-horizon outlook questions (1 day to 1 week) by converting market brief data into quantitative scenario analysis. It clearly distinguishes from the sibling tool `project_net_worth` which handles long-horizon projections.

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 usage guidance: trigger phrases, workflow steps (call get_market_brief first, then construct scenarios), and when NOT to use (long-horizon questions). It also specifies that the caller must supply shocks and disclose them, and directs to `project_net_worth` for months/years projections.

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

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

With no annotations, the description fully discloses behavior: it specifies data sources (Finnhub, Yahoo, FRED), storage format (USD), incremental updates ('increment-only' for fx), and dependencies (API keys). No relevant behavioral aspects are omitted.

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, using three sentences to cover the purpose and all scope details. No redundancy; every word adds value. The structure is logical: general purpose first, then specific scopes, then default.

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

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

For a simple one-parameter tool with no output schema, the description covers all necessary context: what it does, all scope options with detailed explanations, dependencies, and default behavior. It is self-contained and sufficient for correct tool invocation.

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

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

The input schema provides only enum values with no descriptions. The description adds substantial meaning by explaining what each scope does, the data sources involved, and the default behavior. This far exceeds the schema's bare enumeration.

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 refreshes local caches and details each scope option. The verb 'refresh' combined with 'local caches' and explicit scope explanations differentiates it from sibling tools that are primarily for viewing or adding data.

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

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

Description provides clear context for each scope, including data sources and required API keys. While it does not explicitly state when not to use the tool, the context makes it evident that this is for cache refreshing, distinct from other operations.

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