ValuEdge

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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description's one additive signal is that output is evidence, not a trade instruction, which is useful scoping context. It says nothing about latency, rate limits, auth, or data freshness, and the output schema handles return shape.

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, trigger condition front-loaded, zero filler. Every clause either names the data scope or states a boundary.

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 one-parameter read tool with a rich annotation set and an output schema, the description is close to sufficient: return values are documented structurally and safety is covered by annotations. What is missing is ticker format guidance and any disambiguation from get_stock_valuation, which is the sibling an agent is most likely to confuse it with.

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 carries the burden for the single required parameter and does not mention 'ticker' at all. The schema pattern permits characters like '.', '-', '/', ':' and '^', implying exchange-qualified or index symbols, but neither the schema nor the description explains accepted ticker formats or error behavior for unknown symbols.

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 resource's content scope (financial history, profitability, growth, balance-sheet evidence, business quality, data coverage) for a given stock, which lets an agent distinguish it from action-oriented siblings like screen_stocks or analyze_my_portfolio. It never states the operation plainly (retrieve/return) and never names the closest sibling, get_stock_valuation, whose territory overlaps with 'business quality'.

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 opens with an explicit trigger condition ('Use this when the user asks for ...'), which is stronger than most definitions provide. However, the stated exclusion ('Do not use it to infer a trade instruction') concerns interpretation of output rather than tool selection, and no alternative tool is named for the valuation-adjacent cases.

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

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

Annotations 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.