Fair Value Calculator

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

Annotations already declare non-destructive, idempotent, non-open-world. The description adds real value beyond them: the free-tier cap, that listed stocks are left unchanged, the downstream effect on email alerts and the weekly briefing, and that the response reports exactly what changed. Missing only failure behavior (e.g. what happens when the cap is exceeded).

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?

Four short sentences, front-loaded with the action and limits, then the data-source dependency and response behavior. Each sentence adds information; only the repeated 'free accounts up to 10' phrasing costs it a point.

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

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

For a single-parameter mutation with no output schema, the description covers scope, idempotency, side effects on alerts, required input format, and return behavior. Nothing material is missing for an agent to call it correctly.

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

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

Schema coverage is 100% and the single symbol parameter is fully documented in the schema including format examples. The description's 'symbols as returned by resolve_stock' restates the schema rather than adding syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (add) and resource (watchlist) with scope limits (up to 10 on free, unlimited Pro), which cleanly separates it from remove_from_watchlist and get_watchlist. An agent can identify what it does without opening the schema.

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

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

It names the prerequisite data source ('Takes symbols as returned by resolve_stock') and gives the triggering condition ('when the user asks for this change to their own account'). No explicit when-not guidance, but the context is clear enough to route correctly against siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds substantial non-annotation context: Free vs Pro coverage limits (first 2 as snapshots vs 5 with fair values), the derived nature of the values, the disclaimer, and the deep_link escape hatch. It does not describe rate-limit behavior beyond the tier hint.

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

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

Purpose and the use-case condition are front-loaded, which is good, but the deep_link field is explained twice ('deep_link (full analysis page...)' and again 'deep_link opens the full analysis page...') and the field list is dense. The redundancy costs it a point without hurting comprehension.

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

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

With no output schema, the description carries the return-value burden and does so by defining every field (valuation_status with its thresholds, upside_band bands, quality_score range, evidence_level, deep_link). Combined with tier limits and the advice disclaimer, an agent has nearly everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning to the symbols parameter by clarifying that the effective cap is 2 on Free and 5 on Pro, which the schema's maxItems: 5 alone does not convey. The request_id and analysis_session_id parameters are left entirely to the schema.

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

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

States a specific verb and resource ('Compare up to 5 stocks side by side') and immediately scopes it to valuation comparison. It implicitly distinguishes itself from siblings like screen_stocks and get_stock_verdict by naming the exact question type it answers ('which is better valued' about named stocks).

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

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

It gives clear context ('Use it for which is better valued questions about named stocks'), which tells the agent when this tool applies, and implies it is not for screening or single-stock verdicts. It never names an alternative tool or an explicit when-not-to-use condition, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description adds real context: the exact semantics of undervalued/overvalued/near_fair_value/no_valuation thresholds, that values cannot be derived from other fields, and that it is a valuation rather than financial advice. It does not mention rate limits or caching, which is the only notable gap.

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

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

Front-loaded with purpose and routing, which is good, but the deep_link content is stated twice — once in the field list and again in the closing sentence 'deep_link opens the full analysis page with the fair value history chart and every valuation model.' That redundancy costs a point for an otherwise dense paragraph.

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

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

With no output schema, the description carries the return-value burden and does explain every field (valuation_status, upside_band, quality_score, evidence_level, deep_link) plus band formats. It is sufficiently complete for an agent to call and interpret the result, though there is mild overlap with the sibling link semantics typical of this tool family.

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 there is only one parameter, so the schema already fully documents symbol format and fallback resolution. The description adds nothing about the symbol parameter, so the baseline 3 applies.

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

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

States a specific verb+resource ('snapshot for one stock') with scope ('without the exact fair value') and explicitly names the sibling it is not (get_stock_verdict). An agent can distinguish it from compare_stocks and screen_stocks without opening a schema.

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

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

Gives an explicit when-to-use rule ('check many stocks cheaply') and the selecting condition for the alternative ('use get_stock_verdict when the user wants the actual fair value'). No inference required.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: per-account rate limits, the exact limit-exhausted status, the fact that the values cannot be derived from other fields, watchlist side effects, and a not-financial-advice disclaimer. This is unusually rich disclosure for a read 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 critical facts (limit, limit-reached status) are front-loaded and useful, but the description is one long run-on block and repeats the deep_link explanation twice ("fair value history chart" and per-model bear/base/bull case appear in two sentences). It is over-sized for what it communicates.

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

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

There is no output schema, so the description must carry the return contract, and it does: it documents every notable field (valuation_status enum semantics, upside_band bands, quality_score, evidence_level, deep_link, watchlist flag, optional AI fields). An agent can consume the response without further guessing.

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

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

Schema description coverage is 100%, and the schema already explains symbol format, request_id retry de-duplication, and analysis_session_id limit sharing. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ("Full Fair Value Calculator verdict for one stock") and enumerates the payload it returns. It is clearly distinguishable from get_stock_preview, screen_stocks, and the watchlist siblings without opening a schema.

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

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

Gives strong context on when it is callable (free accounts 3/day, Pro 50) and what happens at the limit ("free_daily_limit_reached" with no valuation), which is real routing information. It does not, however, name an alternative such as get_stock_preview for a lighter lookup or state explicit exclusions, so it stops short of full when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond that: Free vs Pro field differences, review_status and flagged_for_review semantics, no_valuation handling with a note explaining why, and the fact that values are model-computed and not derivable from other fields. That is exactly the extra context the annotations cannot carry.

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

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

The purpose is front-loaded and most sentences carry real information, but the paragraph is long and repeatedly restates the same fact: deep_link "opens the full analysis page with the fair value history chart" appears twice, and the closing valuation-model wording duplicates the deep_link clause. Trimming that redundancy would sharpen the definition.

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 must describe the return payload itself, and it does so field by field (valuation_status enums, upside_band bands, quality_score range, evidence_level, deep_link) plus the Free/Pro split and the not-financial-advice caveat. An agent knows what it will receive and how to interpret it.

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

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

There are zero parameters, so per the rubric the baseline is 4; there is nothing for the description to clarify. The schema forbids additional properties, and the description correctly implies no input is needed.

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

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

The first sentence gives a specific verb and resource: read the watchlist saved in the user's Fair Value Calculator account. It clearly states what comes back (stocks, valuation status, upside band, quality score, alert state). It does not name any sibling tool, so an agent gets a clear purpose but no explicit contrast with get_stock_verdict or get_stock_preview.

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

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

It supplies concrete trigger questions ("how is my watchlist valued", "which of my stocks should I review") and notes it works for Free and Pro accounts, which is genuine usage context. It stops short of excluding alternatives or saying when to prefer a sibling such as get_stock_verdict for a single-name deep dive.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds genuinely new context: the previous list is retained as a server-side backup, and the response enumerates exactly what changed. It does not mention error behavior for invalid symbols, so it stops short of full disclosure.

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?

Four short sentences, front-loaded with the core action and cap, then format guidance, then behavioral notes. Minor redundancy between "the user's Fair Value Calculator account" and "their own account," but no wasted 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?

For a single-parameter mutation with no output schema and full annotation coverage, the description covers scope, symbol format, reversibility, and response shape. Only failure modes for bad symbols are unaddressed, which is a minor gap.

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 array shape, min/max items, and item type are already documented. The description still adds cross-tool meaning by telling the agent to pass symbols "exactly as get_watchlist shows them," which is actionable guidance the schema alone does not provide.

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

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

States a specific verb and resource (remove stocks from the watchlist) plus the owning account, which immediately distinguishes it from the add_to_watchlist sibling. The 10-item cap and the get_watchlist reference further pin down the operation.

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

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

"Use it when the user asks for this change to their own account" gives clear positive usage context and implicitly routes away from read-only siblings like get_watchlist. It stops short of naming add_to_watchlist as the inverse or stating when not to use it, so no explicit exclusions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description goes beyond them by disclosing result cardinality ('up to 5 matches'), result ordering that mirrors the website search, and the meaning of every returned field, including the enum semantics of valuation_status and the banding scheme of upside_band. It does not say what happens on a zero-match query, which keeps it from a 5.

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

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

Purpose and usage are front-loaded in the first two clauses; the remaining length is a field glossary that is justified because no output schema exists. No filler sentences.

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

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

With no output schema, the description carries the full burden of explaining returns, and it does so thoroughly (symbol, name, valuation status, bands, quality, evidence, deep link). Missing only edge-case behavior such as zero or ambiguous multi-match results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds that the query accepts not just a name or ticker (as the schema says) but also 'ISIN-like input', and frames the input as resolving to an exact TICKER.EXCHANGE listing.

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

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

States a specific verb (find/resolve), resource (listed company), input modes (name, ticker, ISIN-like), and the exact scope (up to 5 matches from the 35,000+ covered universe). It is clearly distinguishable from siblings like get_stock_preview and get_stock_verdict, which consume the symbol this tool produces.

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

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

Explicitly says when to reach for it: 'when the user names a company or the exchange is unclear', and explains the downstream value ('symbol to pass to the other tools'). It stops short of naming alternatives or stating when not to use it (e.g. when a symbol is already known), so it is clear context without full routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description does add useful non-annotation context: ranking by quality score, tier-based caps (Free top 3, Pro up to 20), that the result is the complete answer, and a disclaimer that this is a valuation, not advice. Behavior is only partially disclosed - rate-limit behavior is left to the schema's request_id/analysis_session_id rather than explained in prose.

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

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

The purpose is front-loaded well, but the field enumeration is bulky and the deep_link explanation is largely repeated ('deep_link (full analysis page on fairvalue-calculator.com...)' followed later by 'deep_link opens the full analysis page with the fair value history chart'). That redundancy costs efficiency.

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

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

With no output schema, the description carries the burden of explaining return values and it does so thoroughly: valuation_status thresholds, upside_band semantics, quality_score range, evidence_level, and deep_link. Tier limits and the next-step pointer to deep_link make it actionable; only error/failure behavior is unexplained.

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 documents all 7 parameters including defaults for min_quality and min_upside_pct. The description adds semantic depth for returned fields rather than parameters, and only indirectly ties the tier caps to 'limit'. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Find stocks that currently match valuation criteria') and adds a scope qualifier ('from Fair Value Calculator data only') that separates it from unrelated screening. It does not explicitly name a sibling tool to differentiate from (e.g. get_stock_verdict or suggest_watchlist_stocks), so it falls short of a 5.

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

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

Concrete trigger examples are given ('which stocks are undervalued right now', 'undervalued European tech stocks'), which tells the agent when to reach for this tool. No when-not conditions or named alternatives are provided, so no exclusions to guide the agent away.

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

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

Annotations already declare the write/idempotent/non-destructive profile, and the description adds real context beyond them: the alert fires on a hold-to-sell valuation signal change, the Pro gating, and that the response lists exactly what changed. It doesn't cover auth or delivery specifics, but it goes well past the annotation surface.

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

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

Front-loaded with the action, then scope, mechanism, and usage in short declarative sentences. Slightly more detail than strictly needed (the hold-to-sell explanation), but every sentence contributes information an agent would otherwise lack.

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

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

For a single-parameter toggle with no output schema, the description covers action, scope, gating, trigger condition and response shape ('lists exactly what changed'), while annotations carry the safety profile. Nothing essential to a correct call is missing.

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

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

With one parameter at 100% schema coverage, the schema already documents the boolean toggle. The description nonetheless adds semantic scope the schema lacks: that the toggle governs email alerts for the entire watchlist rather than individual stocks, which is meaningful for correct invocation.

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

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

States a specific verb (turn on/off), resource (watchlist email alerts) and scope (whole watchlist, not single stocks), which cleanly separates it from the per-stock siblings like add_to_watchlist and get_stock_verdict. An agent can identify the operation without opening the schema.

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

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

Gives a clear trigger ('Use it when the user asks for this change to their own account') and a scope exclusion ('covers the whole watchlist, not single stocks'; 'no price-target alerts'). It stops short of naming a sibling alternative for per-stock alert changes, so it is strong but not fully explicit about when-not.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces with 'Nothing is changed' plus the ranking logic and correlation range (-1 to +1). It adds real context about how suggestions are generated, though 'Nothing is changed' largely echoes readOnlyHint.

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

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

Front-loaded with the core purpose, but the tail is bloated: deep_link is described twice ('full analysis page... with the fair value history chart and the result of each valuation model' then repeated almost verbatim), and the fair-value derivation point is restated. Several sentences could be consolidated.

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, and the description does the work of documenting return fields: valuation_status with its enum semantics, upside_band banding format, quality_score range, evidence_level, deep_link, and correlation_to_watchlist. An agent can interpret results without further documentation.

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 meaning beyond the schema by explaining that 'replace' causes the suggestions to match the size of that stock and that ranking is driven by correlation, which the schema's terse parameter text does not convey.

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

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

States a specific verb (suggest) and resource (stocks fitting the saved watchlist) along with the exact eligibility criteria: below fair value, high quality, not yet on watchlist, ranked by quality/undervaluation/correlation. This differentiates it cleanly from siblings like screen_stocks and add_to_watchlist.

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

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

Gives concrete trigger phrases ('what would diversify my watchlist', 'what could replace Home Depot'), explains that a 'replace' request sizes the suggestions to that stock, and explicitly routes the mutation case to add_to_watchlist. When-to-use and an alternative are both named.

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