ValuEdge Stock Research MCP

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds a genuine behavioral constraint beyond that: output must explain evidence and limitations and must not issue buy/sell/hold instructions. It does not mention auth requirements or any rate/scope 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 sentences, no filler: the trigger condition is front-loaded and the behavioral constraint follows. The dense trigger list is long but every clause maps to a distinct analysis type rather than padding.

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 described, and annotations carry the safety profile. Purpose, usage context, and output-style constraints are all present; the only real gap is the meaning of the optional portfolio_name parameter.

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 single optional, nullable parameter portfolio_name is never mentioned. The description gives no hint that omitting it selects a default portfolio, which is the key ambiguity an agent faces here. With one undocumented param the description should compensate, and it does not.

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 enumerates the concrete analyses produced (concentration, sector/currency allocation, fair-value coverage, risk context), which lets an agent distinguish it from the raw-retrieval sibling get_my_portfolio. It never states the verb 'analyze' outright, but the enumerated outputs make the resource and scope 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?

It gives an explicit trigger ('when the authenticated user asks for their own portfolio...') and scopes it to the authenticated user's own data, implicitly excluding other users' portfolios and other siblings. It stops short of naming an alternative (e.g., get_my_portfolio for raw holdings) or stating 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds a genuine output constraint — no winner verdict and no buy/sell/hold advice — which is not derivable from annotations. It says nothing about auth requirements, rate limits, or what happens with an unconfirmed ticker.

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. The trigger condition comes first and the output restriction second, both earning their 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?

With an output schema present, return-value explanation is not required, and the description covers trigger, scope, dimensions and output guardrails. It is slightly thin on what happens when a ticker is invalid or not covered, which matters for an openWorld multi-input tool.

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

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

Schema description coverage is 0% for the single tickers array, so the description must carry the load. It does: it states the 2–6 ticker range the array enforces and adds the qualifier "confirmed," implying tickers must be validated before comparison — a semantic the schema's regex alone 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 (compare) and resource (stock tickers) plus the exact scope (two to six confirmed tickers) and the dimensions compared (valuation, growth, quality, market metrics, assumptions, coverage). This multi-ticker comparison framing inherently separates it from single-ticker siblings like get_stock_valuation and get_stock_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 an explicit trigger ("Use this when the user asks to compare...") and a behavioral exclusion ("Do not declare a universal winner or give buy, sell, or hold instructions"). It does not name competing siblings such as screen_stocks or analyze_my_portfolio, so the agent must infer the boundary between comparison and screening.

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, closed-world, so the safety profile is covered. The description adds genuinely useful scoping context beyond that: it never accepts a user id and never returns another user's data, which tells the agent about authorization boundaries and confirms there is no cross-user leakage.

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: the usage trigger is front-loaded and the access boundary follows. Every clause carries information an 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 values need not be described, and annotations cover the safety profile. The remaining gap is the optional portfolio_name selector, which is undocumented in both schema and description — an agent cannot tell whether omitting it returns all portfolios or a default one.

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 parameter portfolio_name, so the description carries the full burden and fails to mention it at all. It never explains whether the name selects one portfolio among several, what happens when it is null (the schema allows null), or what valid values look like.

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 gives a specific verb+resource (review the authenticated user's own ValuEdge portfolio) and enumerates the content it covers: holdings, market value, fair-value coverage, allocation, concentration, risk context. It does not explicitly distinguish itself from the very similar sibling analyze_my_portfolio, so an agent must guess which to pick when the user asks for analysis rather than a plain read.

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 is an explicit use-when trigger ('when the authenticated user asks to review their own... portfolio'), which is stronger than most tool descriptions. However, no alternative is named or excluded, and analyze_my_portfolio sits directly adjacent in the sibling list with no guidance on which to choose.

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/destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond them: a per-user privacy boundary ('never exposes another user's alerts') and confirmation that alert state is not mutated. It does not mention pagination or result shape, but that is minor here.

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

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

Two sentences, zero filler, with the trigger condition front-loaded and the privacy constraint following. Nothing needs trimming.

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 no explanation, and the purpose/privacy story is complete. However, with 0% schema coverage the description should say something about the limit and state parameters, and 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 description coverage is 0% and neither parameter is named in the description. The phrase 'changes alert state' hints that 'state' refers to alert state, but the 'limit' parameter is entirely undocumented in both schema and description, leaving an agent to guess its meaning and default.

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 (review Smart Alerts) plus the scope (the authenticated user's own alerts and their valuation context). It is clearly distinct from get_my_portfolio/get_my_watchlist by naming the 'Smart Alerts' resource, though it never explicitly contrasts itself with those 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?

'Use this when the authenticated user asks to review their own ValuEdge Smart Alerts' gives a clear trigger condition. It stops short of naming an alternative tool or stating when not to use it, but the usage context is unambiguous.

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 non-destructive behavior, so safety is covered; the description adds the meaningful authorization scoping rule that only the authenticated user's own watchlist is ever returned. It also signals the freshness/valuation context of the payload, which is genuinely beyond the annotations, but says nothing about pagination or size 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?

One front-loaded sentence beginning with 'Use this when' giving the trigger, then the payload contents and the auth constraint, with no filler. The enumerated field list is slightly long but each item earns its place by telling the agent what to expect.

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 need not be described (the description lists them anyway), and annotations cover the safety profile, so the core need is met. However, for a tool whose only parameter is completely undocumented in both schema and description, the definition leaves a real gap about default watchlist behavior.

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% and the single optional 'watchlist_id' parameter is never explained: whether omitting it (or passing null) returns a default watchlist, or how multiple watchlists are disambiguated, is unspecified. The sentence 'Never accepts a user id' clarifies only that the parameter is not a user identity and arguably raises a question about what it actually is.

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 fields (price, fair value, margin of safety, quality signals, freshness), so the agent knows exactly what this tool produces. It is distinguishable from get_my_portfolio and get_my_smart_alerts by the 'watchlist' resource, though it does not explicitly contrast itself with those 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?

Gives a clear trigger condition ('when the authenticated user asks to review their own watchlist') plus a negative constraint ('Never accepts a user id'), which implicitly rules out per-user or impersonation requests. It stops short of naming an alternative sibling for the portfolio or alerts case, so routing between siblings is left partly to inference.

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

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

Annotations already carry readOnly/idempotent/non-destructive, so the description's job is to add data-quality context, which it does well: EPS is not normalized, past estimate revisions are unavailable, missing source rows/provenance are reported rather than filled, and consensus is capped at three future fiscal years. These are exactly the caveats an agent needs to avoid overclaiming, though it stops short of describing scale or latency 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 trigger sentence is front-loaded and clean, but the middle sentence is an overstuffed run-on chaining four separate data-scope clauses that would read far better as a list. Little is wasted informationally, but the structure makes the payload hard to parse on first read.

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 description need not explain return shapes, and it still covers scope, the optional history parameter's effects, and the main data-integrity caveats. The remaining gap is the undocumented ticker format constraint, which is only enforced by a schema pattern.

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 only 50% (ticker is undocumented in-schema), but the description compensates by explaining what history_limit actually unlocks: up to 30 periods of selected metrics, quarterly P/E samples derived from monthly observations, and bounded source-native statement rows. The ticker parameter's accepted format lives only in the schema pattern, so the description does not fully carry the undocumented half.

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 concrete resource (ValuEdge financial history: profitability, growth, balance sheet, business quality, coverage) so an agent knows this retrieves fundamental data rather than prices or valuations. It does not explicitly contrast itself with the sibling get_stock_valuation, which is the nearest ambiguity, 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?

The opening clause 'Use this when the user asks for...' gives a clear trigger condition tied to user intent categories. It offers no explicit when-not or named alternative (e.g., use get_stock_valuation for price multiples), though the closing 'Do not infer a trade instruction' usefully bounds downstream use.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the scope boundary (single stock, public data, not the user's portfolio), which is useful behavioral context, but says nothing about caching, data freshness, or failure modes for unknown tickers.

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 no filler, and the usage trigger is front-loaded ahead of the exclusion. It is efficient and nothing is redundant, though the second sentence does the routing work that the first could have woven in.

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 description does not need to describe return values, and the annotations carry the safety profile, so the scope note plus the enumerated outputs cover most of what an agent needs. The only real omission is any guidance on the ticker format, the one thing the schema leaves at 0% description coverage.

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 the ticker parameter, its accepted formats (dotted classes, index carets, exchange suffixes), or case sensitivity, even though the schema's pattern allows 'BRK.B', '^GSPC' and 'NYSE:IBM' style values. The description therefore adds no meaning beyond the bare schema field name.

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 specific resource (ValuEdge fair value for one stock) and enumerates the concrete outputs it returns: current price, margin of safety, valuation method, assumptions, confidence, and valuation risk. It also distinguishes itself from the portfolio siblings by stating it is not for a user's private portfolio, so an agent can route between it and get_my_portfolio 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?

It gives an explicit trigger ('when the user asks for one stock's ... fair value') and an explicit exclusion ('Do not use it for a user's private portfolio'), which is more than most definitions offer. It stops short of naming the alternative tool to use instead (get_my_portfolio), so it is clear context rather than fully closed 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 readOnly/idempotent/openWorld/non-destructive, and the description layers substantial extra behavior on top: a 60-candidate window with at most 12 returned rows, presets that only become stricter, a custom baseline requiring >=300M market cap and valid canonical fair value, and an instruction to disclose incomplete results, source dates, missing coverage and negative-equity caveats. That is materially more than the annotations provide.

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 a clear 'Use this when...' trigger, and the sentences are dense but purposeful. It is long for a description, with some near-redundancy against the schema (e.g., 'Presets only become stricter' echoes the filter object's description), but nothing is padding.

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 no explanation; within that constraint the description still covers the bounded result window, the baseline conditions, preset-vs-custom behavior, and disclosure caveats an agent must relay. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 60%, so the schema carries much of the per-filter burden, but the description adds real meaning: percentages are decimal fractions, the AND-conjunction only tightens a preset, and the custom baseline imposes implicit constraints (market cap floor, valid canonical fair value) that shape which filters are meaningful. It does not restate every filter, which 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 names a specific verb+resource (a bounded stock screen) and enumerates concrete use cases (undervalued, quality, dividend, large-cap, positive-FCF), so an agent immediately knows what the tool returns. It scopes the tool as a bounded candidate window rather than an exhaustive scan, but it never names or contrasts the adjacent siblings (search_securities, get_stock_fundamentals), so sibling differentiation is left to inference.

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?

Strong internal guidance: 'Use this when the user wants a bounded ... screen,' choose a preset or compose filters, use the smallest faithful filter set, and state chosen thresholds. It also gives explicit exclusions ('Arbitrary database queries and trade instructions are not supported'). The only gap is that it never says when to prefer this over search_securities or get_stock_valuation.

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 closed-world behavior, so the safety profile is covered. The description adds one genuinely useful constraint — search is bounded to the ValuEdge-supported security universe — but says nothing about result limits, ranking, or match counts.

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, and the when-to-use condition is front-loaded ahead of the scoping constraint. Every clause 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?

With an output schema present, return values need not be described, and annotations cover the safety profile; the description supplies the usage trigger and the closed-universe constraint. For a single-parameter lookup tool this is nearly complete, missing only matching/limit behavior.

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%, so the description must carry the load, and it does clarify that the single query parameter accepts either a company name or a ticker and may be ambiguous. It omits the length bounds and any matching syntax, so compensation is only partial.

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 action (resolve an ambiguous company name or ticker) and a concrete resource (securities), which is more precise than the bare title. It is distinguishable from siblings like screen_stocks or get_stock_valuation, though it never explicitly contrasts itself with them by name.

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 a clear triggering condition: use when the user supplies an ambiguous company name or ticker and resolution is needed before valuation or comparison. This routes the agent correctly, but it stops short of naming alternates (e.g. screen_stocks) or stating 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.