ValuEdge MCP provides public, anonymous stock research: security search, fundamentals, valuation, comparisons, and preset-based screening. With ValuEdge authentication, it provides read-only access to the signed-in user's private portfolio, watchlist, and Smart Alerts. Research only; not investment advice.
Scored across 9 tools
Most tools target clearly distinct resources (valuation, fundamentals, screening, search, watchlist, alerts), but analyze_my_portfolio and get_my_portfolio are described with nearly identical language — holdings, market value, fair-value coverage, allocation, concentration, risk context — leaving an agent with no clear rule for which to call. The remaining tools are well separated by explicit 'use this when' guidance.
All nine tools follow a predictable snake_case verb_noun pattern, with a coherent ownership convention (get_my_*, get_stock_*) that communicates scope. The single 'analyze' verb alongside 'get' is a meaningful distinction rather than a convention break.
Nine tools is well within the ideal range and each maps to a distinct user intent: resolve a ticker, value a stock, check fundamentals, compare, screen, and inspect one's own portfolio, watchlist, and alerts. No filler tools are present.
The read-side surface is thorough for a valuation research domain: search, valuation, fundamentals, comparison, screening, plus private portfolio, watchlist, and alert reads. Gaps exist on the write side — no way to add/remove watchlist entries or create/update smart alerts — which agents will hit when users ask to act on findings.
Use this when the authenticated user asks for their own portfolio concentration, sector or currency allocation, fair-value coverage, or risk context. Explain evidence and limitations without giving buy, sell, or hold instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| portfolio_name | No |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds behavior beyond that: the response should surface evidence and limitations and must not issue investment advice, which is real output-shaping context an agent would not infer from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, with the activation condition front-loaded before the advisory constraint. Every clause carries information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is unnecessary, and the read-only nature is covered by annotations. The remaining gap is the undocumented portfolio_name parameter and the absence of any statement about default scope or behavior when the named portfolio doesn't exist.
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 single optional parameter portfolio_name has 0% schema description coverage and is not mentioned anywhere in the description. An agent cannot tell whether omitting it means 'the default portfolio' or 'all portfolios', nor how to use it to disambiguate when a user holds multiple portfolios.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb-and-resource pair (analyze the authenticated user's portfolio) and enumerates the exact analytical dimensions returned: concentration, sector/currency allocation, fair-value coverage, and risk context. That makes it clearly distinct from retrieval siblings like get_my_portfolio or market-wide tools like screen_stocks, though it never names those siblings explicitly.
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 an explicit activation trigger — 'when the authenticated user asks for their own portfolio concentration...' — which is a concrete use context, and adds a guardrail against producing buy/sell/hold recommendations. It stops short of stating when NOT to use it or naming the alternative tool when the user wants the other user's portfolio or raw holdings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks to compare two to six stocks on current price, canonical fair value, margin of safety, confidence, valuation risk, and fair-value coverage. This tool compares valuation only; use get_stock_fundamentals separately for growth, profitability, or balance-sheet claims. Do not declare a universal winner or give buy, sell, or hold instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| tickers | Yes |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds non-obvious behavioral scope: the comparison is valuation-only and the output must not be framed as a recommendation. It does not discuss data freshness, partial coverage handling, or error behavior for invalid tickers, so it stops short of 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?
Three tightly packed sentences, front-loaded with the trigger condition, then the sibling exclusion, then the output guardrail. The final sentence addresses the agent's response style rather than the tool's mechanics, which is useful but slightly outside the tool's contract and keeps this from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is unnecessary, and the single input parameter is self-describing in the schema. With annotations covering safety and idempotency, the description supplies everything else an agent needs: when to call it, what it covers, where to go instead, and how to frame 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?
Only one parameter, whose constraints (minItems 2, maxItems 6, pattern, maxLength) are fully encoded in the schema even though schema_description_coverage is 0%. The description restates 'two to six stocks' but adds no ticker-format or identifier meaning beyond the schema, so this is the baseline adequate score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (compare) and resource (stocks) with an explicit cardinality bound (two to six) and enumerates the exact dimensions compared (price, fair value, margin of safety, confidence, valuation risk, coverage). This clearly separates it from get_stock_valuation (single stock) and get_stock_fundamentals (non-valuation fundamentals).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives the triggering condition ('when the user asks to compare two to six stocks') and names the sibling to use instead for out-of-scope needs ('use get_stock_fundamentals separately for growth, profitability, or balance-sheet claims'). It also states a hard prohibition (no universal winner, no buy/sell/hold), which is exactly the kind of when-not guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the authenticated user asks to review their own ValuEdge portfolio, holdings, market value, fair-value coverage, allocation, concentration, or risk context. Never accepts a user id and never returns another user's data.
| Name | Required | Description | Default |
|---|---|---|---|
| portfolio_name | No |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the bar is low. The description nonetheless adds a genuine behavioral guarantee beyond the annotations: it never accepts a user id and never returns another user's data, which is a meaningful scoping/security constraint for an agent. It omits what happens when no portfolio exists, but that is minor.
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, zero filler, with the usage trigger front-loaded before the scoping constraint. Every clause carries 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?
An output schema exists, so return-value explanation is not required, and annotations cover the safety profile. What remains missing is the interpretation of the single optional parameter and the disambiguation from 'analyze_my_portfolio', so the definition is nearly but not fully self-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 description coverage is 0% and the description never mentions 'portfolio_name' at all. Because the parameter is optional and nullable, the crucial question — whether null means default portfolio, all portfolios, or aggregate — is answered nowhere, so the description does not compensate for the coverage gap.
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?
It states a specific verb-plus-resource ('review their own ValuEdge portfolio') and enumerates the facets returned (holdings, market value, fair-value coverage, allocation, concentration, risk). It stops short of differentiating itself from the sibling 'analyze_my_portfolio', which sounds like the same resource and leaves the agent guessing which to pick.
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 opening clause gives an explicit trigger condition ('when the authenticated user asks to review their own... portfolio'), which is far beyond implied usage. However, it names no exclusions and never mentions the nearby 'analyze_my_portfolio' alternative, so the boundary between retrieval and analysis is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the authenticated user asks to review their own ValuEdge Smart Alerts and the valuation context behind them. Never exposes another user's alerts or changes alert state.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| state | No |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine context beyond that: strict per-user scoping and the guarantee that alert state is never mutated. It stops short of describing result volume or how paging behaves relative to the limit parameter.
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 tight sentences with the usage trigger front-loaded and the boundary guarantees after it. No filler, no restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the read-only, own-data contract is clear. The missing piece is the state filter: for a two-parameter list tool where the only meaningful filter has an open-ended string type, the definition leaves the agent guessing at valid inputs.
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 0% for two parameters, and the description compensates for neither. The free-text 'state' filter (anyOf string up to 40 chars) is left completely undefined — an agent has no idea what values are valid — and 'limit' is only implied by nothing at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource ('ValuEdge Smart Alerts and the valuation context behind them') and the act of reviewing them, so the intent is unambiguous. The 'my' scoping distinguishes it from the portfolio/watchlist siblings, though it never explicitly contrasts with 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?
'Use this when the authenticated user asks to review their own...' gives a clear triggering condition. It also gives exclusions — never exposes another user's alerts, never changes alert state — but does not point at any sibling alternative for related tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the authenticated user asks to review their own ValuEdge watchlist, including current price, canonical fair value, margin of safety, quality signals, and data freshness. Never accepts a user id.
| Name | Required | Description | Default |
|---|---|---|---|
| watchlist_id | No |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | |
| metadata | Yes |
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 fully covered. The description's only genuine behavioral addition is the scoping rule that no user id is accepted, which implies implicit auth-derived context; it says nothing about pagination, limits, or size of results. That is modest value on top of annotations, so a 3.
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?
One usage sentence followed by a short constraint, with the when-to-use condition front-loaded. Every clause carries information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Because an output schema exists, the enumerated return fields are largely redundant, and the annotations cover the read-only profile. The remaining real gap is the optional watchlist_id: without semantics for it or a stated default, an agent cannot say what happens when it is left out of the call.
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 0% for the single optional 'watchlist_id' parameter. The description only obliquely clarifies the id space by ruling out a user id; it never says what a watchlist_id looks like or what happens when it is omitted or null. With one undocumented parameter, this falls below the 3 baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('review their own ValuEdge watchlist') and enumerates the returned content (price, fair value, margin of safety, quality signals, freshness). The watchlist resource is plainly distinct from the sibling portfolio, alerts, and valuation tools, so an agent can route 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?
'Use this when the authenticated user asks to review their own ... watchlist' gives a clear triggering condition, and 'Never accepts a user id' sets a boundary. It stops short of naming an alternative for related-but-different requests (e.g. portfolio vs watchlist routing guidance), so it lands at 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks for a stock's ValuEdge financial history, profitability, growth, balance-sheet evidence, business quality, or data coverage. An optional history_limit requests up to 30 periods of selected metrics, current EPS consensus for at most three future fiscal years where present, quarterly P/E samples from existing monthly observations, and bounded source-native annual income, balance-sheet, and cash-flow statement rows where the existing snapshot contains them. EPS is not normalized and past estimate revisions are unavailable. Selected metric trends remain distinct from the full annual statement JSON. Do not infer a trade instruction.
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes | ||
| history_limit | No | Optional maximum number of recent annual/quarterly selected-metric rows and annual statement rows (1–30). Omit to preserve the existing compact response. Full annual statement rows retain source fields and currencies; missing source rows/provenance are reported, never filled. Current EPS consensus is capped separately at three future fiscal years; it is not normalized and past revisions are unavailable. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, openWorld and non-destructive, and the description adds real data-quality context beyond them: EPS is not normalized, past estimate revisions are unavailable, missing source rows are reported rather than filled, and selected metric trends are distinct from the full statement JSON. It stops short of stating response size, latency, or auth requirements.
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 use-when trigger is properly front-loaded, but the second sentence is an overstuffed run-on enumerating four separate response behaviors, and the 'EPS is not normalized and past estimate revisions are unavailable' clause is repeated verbatim-ish from the schema. Several clauses could be cut without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values needn't be explained, and the description covers trigger conditions plus key data limitations (unnormalized EPS, no revisions, no backfill of missing rows). For a two-parameter read tool this is nearly complete; only sibling routing guidance is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: the ticker parameter is undocumented but self-evident from name and pattern, while history_limit already has a thorough schema description. The description's history_limit sentences largely restate the schema (30-period cap, three-year EPS consensus cap, non-normalized EPS) rather than adding meaning, so this sits at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (a stock's financial history, profitability, growth, balance-sheet evidence, business quality, data coverage) and frames it as a retrieval keyed to a ticker, which an agent can distinguish from get_stock_valuation or compare_stocks. It never states a clean verb like 'retrieve' and leans on the scenario framing, so it is clear but slightly indirect.
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 an explicit when-to-use trigger ('Use this when the user asks for a stock's ... financial history ...') and an explicit behavioral boundary ('Do not infer a trade instruction'). It does not name alternative siblings or say when not to use it, so routing to get_stock_valuation vs. this tool is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user asks for one stock's ValuEdge fair value, current price, margin of safety, valuation method, assumptions, confidence, or valuation risk. official_fair_value_source identifies the upstream model/component, while valuation_method_label describes headline composition, so a DCF source can accompany a blended headline. specialist_model.fair_value_blend is the optional source-provided equity-model breakdown and may be null when unavailable; blending_applied is independently reconciled from valid top-level canonical DCF/multiples values and weights. Do not use it for a user's private portfolio.
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | |
| metadata | Yes |
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 description wisely spends its space on data semantics instead: it discloses that specialist_model.fair_value_blend may be null, and that blending_applied is reconciled independently from top-level DCF/multiples values while valuation_method_label can describe a blended headline from a DCF source. These are non-obvious provenance traits an agent could not infer from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Usage trigger is front-loaded in the first clause, followed by field disambiguation; there is no filler. The middle sentence on official_fair_value_source vs valuation_method_label is dense jargon but earns its place as an anti-confusion note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the tool is largely self-documenting, yet the description invests most of its length in return-field semantics while leaving input handling (invalid or unknown ticker, symbol normalization, market coverage) unaddressed. Adequate to call correctly, but not complete for a query tool where a bad symbol is the most likely failure mode.
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 single parameter (ticker) has 0% schema description coverage, so the description carries the full burden here — but it says nothing about ticker format, exchange suffix, or accepted symbol conventions (e.g. BRK.B, ^GSPC) allowed by the pattern. "One stock's" only weakly implies a single symbol argument.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the resource precisely and enumerates the exact fields it returns (fair value, price, margin of safety, method, assumptions, confidence, risk), which pins down scope well. It differentiates only from the private-portfolio case, not from the nearest sibling get_stock_fundamentals, so an agent still has to infer that boundary.
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 this when the user asks for one stock's ValuEdge fair value..." is a concrete trigger condition, and "Do not use it for a user's private portfolio" states an explicit exclusion. The exclusion does not name the correct alternative (get_my_portfolio / analyze_my_portfolio), leaving the redirect implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants a bounded ValuEdge stock screen for research candidates such as undervalued, quality, dividend, large-cap, or positive-free-cash-flow stocks. Sign in or create a free ValuEdge account before screening; current account quotas and plan entitlements apply. Choose a preset or compose supported filters for undervalued growth and other requests. Use the smallest faithful filter set and state chosen growth/valuation thresholds. Percentages are decimal fractions (0.15 = 15%). Presets only become stricter. The custom baseline requires market cap >=300 million in listing currency and valid canonical fair value. Screening is for NYSE/NASDAQ stocks with a 60-candidate window and at most 12 returned rows, not an exhaustive market scan; disclose incomplete results, source dates, missing coverage and negative-equity caveats. Arbitrary database queries and trade instructions are not supported.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| sector | No | ||
| filters | No | Optional conjunction (AND) of 1–24 public controls. Only tightens the selected preset; cannot remove its stock-only, exchange, market-cap, or fair-value baseline. Percentages are decimal fractions. Unsupported fields/operators are rejected. | |
| preset_id | No | Defaults to undervalued for preset-only calls, or custom when filters are supplied. Explicit presets retain their baseline conditions. | |
| growth_comparison | No | For all growth minimums in a custom-filter call: gte means at least (default); gt means strictly greater. Other operators follow each field description: ratio/yield minimums are strict >, positive-multiple maximums are strict <, debt/equity and dividend-yield maximums are <=, and market-cap/score/MOS bounds are inclusive. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it read-only, open-world, idempotent and non-destructive, and the description adds substantial context beyond them: a 60-candidate window, at most 12 returned rows, presets only become stricter, the custom baseline (market cap >=300M plus canonical fair value), NYSE/NASDAQ limitation, and required disclosure of coverage gaps and source dates. This gives an agent the full operating picture of a screening call.
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 use case and constraint sentences are dense but each carries policy an agent needs (auth, limits, disclosure duties). A few clauses are run-on (the final disclosure sentence bundles several caveats), so it is not maximally clean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return shape needn't be described. Combined with annotations, the description covers activation, auth, quotas, filtering semantics, universe bounds, preset behavior, and disclosure obligations — everything needed to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60% and the filter fields are individually well documented, but the description adds genuinely useful semantics: decimal-fraction conventions (0.15 = 15%), presets retaining baseline conditions, baseline thresholds, and the 'smallest faithful filter set' instruction. It doesn't cover growth_comparison explicitly, leaving that to the schema, so slightly below top marks.
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 ('bounded ValuEdge stock screen for research candidates') and enumerates the screen types (undervalued, quality, dividend, large-cap, positive-FCF). This clearly separates it from sibling read tools like get_stock_fundamentals and compare_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?
Gives explicit trigger ('when the user wants a bounded ValuEdge stock screen'), prerequisites (sign in / create a free account, quotas and entitlements apply), and exclusions ('Arbitrary database queries and trade instructions are not supported'). Also guides toward presets vs. custom filters and the smallest faithful filter set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user gives an ambiguous company name or ticker and you need to resolve it before valuation or comparison. Search is limited to the ValuEdge-supported security universe.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| data | No | |
| error | No | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful scope by noting the search is limited to the ValuEdge-supported security universe, but it does not describe result ranking, limits, or matching 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 two sentences and front-loads the usage condition. Every sentence contributes either the triggering scenario or the important universe limitation.
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 low complexity, rich annotations, and the presence of an output schema, the description covers the essential context: when to use it, what it resolves, and its closed universe. Minor gaps remain around matching behavior and result presentation, but return values are handled by the 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?
With only one required parameter and 0% schema description coverage, the description partially compensates by saying the query is an ambiguous company name or ticker. It does not clarify matching behavior, partial input support, or ticker formatting, so it adds meaning but not enough to fully cover the schema gap.
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: searching securities to resolve an ambiguous company name or ticker. It distinguishes the tool from valuation/comparison siblings by placing it before those steps, though it does not explicitly name the alternatives.
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 usage guidance: use this when the user supplies an ambiguous company name or ticker and you need to resolve it before valuation or comparison. It does not explicitly state when not to use it or name alternative sibling tools, which keeps it from a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_stock_fundamentals1 field changedInput schema / properties / history_limit / descriptionPrevious value: -"Optional maximum number of recent annual, quarterly, and quarterly P/E history rows (1–30). Omit to preserve the existing compact response. Provider-reported EPS consensus is capped separately at three future fiscal years; it is not normalized and past revisions are unavailable."New value: +"Optional maximum number of recent annual/quarterly selected-metric rows and annual statement rows (1–30). Omit to preserve the existing compact response. Full annual statement rows retain source fields and currencies; missing source rows/provenance are reported, never filled. Current EPS consensus is capped separately at three future fiscal years; it is not normalized and past revisions are unavailable."get_stock_fundamentals1 field changedInput schema / properties / history_limitAdded value: +{
+ "description": "Optional maximum number of recent annual, quarterly, and quarterly P/E history rows (1–30). Omit to preserve the existing compact response. Provider-reported EPS consensus is capped separately at three future fiscal years; it is not normalized and past revisions are unavailable.",
+ "maximum": 30,
+ "minimum": 1,
+ "type": "integer"
+}analyze_my_portfoliocompare_stocksget_my_portfolioget_my_smart_alertsget_my_watchlistget_stock_fundamentalsget_stock_valuationscreen_stockssearch_securities
Add one secure layer between your agents and this server.