HPSILab Quant Finance

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses partial-failure semantics (status "partial" when one source is gated/unavailable/errors) versus whole-call failure (status "error", isError=True), plus the cache-vs-fresh behavior driven by `refresh`. That is exactly the kind of failure-mode context an agent needs before invoking an aggregator.

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

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

The purpose sentence is front-loaded and the partial/error paragraph earns its place. The closing clause of the `lang` doc ("so an existing caller that omits this gets byte-identical output to before") is backwards-compatibility trivia that mildly pads an otherwise tight definition.

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

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

For an aggregator with three parameters, an output schema, and rich annotations, nothing material is missing: inputs are fully explained, failure modes are specified, and the returned fields are summarized (which the output schema then details). An agent can invoke this correctly from the description alone.

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: `symbol` gets a concrete example, `refresh` is explained as bypassing the backend IV cache, and `lang` lists accepted values (en/zh/ja, regional forms like zh-CN) plus which fields it affects. All three parameters are documented with meaning the schema lacks.

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?

"Aggregate all quant tools into one JSON stock analysis" is a specific verb+resource, and the following sentences name the concrete outputs (direction signal, score, bullish/bearish factors, summary). It implicitly distinguishes itself from the granular siblings by saying it reuses them as data sources, but never names them, so the differentiation is inferential rather than explicit.

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 aggregation-over-siblings intent is implied by "reuses the existing MCP tools as its data sources", which suggests using this instead of calling get_iv_radar, get_ai_prediction, etc. individually. However, there is no explicit when-to-use/when-not statement and no guidance on when a single-component sibling is preferable to the aggregate bundle.

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=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds useful behavioral context: it returns URLs, reuses the Growth Engine image generators, and explains that force controls cache regeneration. Rate limits or cost implications are not mentioned, so it falls 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?

The description is front-loaded and uses a clear Args structure with no wasted opening. The implementation note about reusing Growth Engine generators is useful context but slightly less essential than the rest, keeping it below 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 values need not be explained, and annotations cover the safety profile. The description covers all parameters and the key separation from analyze_stock, but it does not address how this relates to the similarly named get_* chart siblings.

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%, but the description fully documents all three parameters. It gives a symbol example, explains that force bypasses cached PNGs and defaults to True for fresh data, and lists every allowed chart type while explaining that omitting types generates all of them.

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: 'Generate stock-report PNG images and return their URLs.' It explicitly separates the tool from analyze_stock, but it does not clearly differentiate it from the get_* chart-data siblings such as get_ai_prediction or get_equity_curve.

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

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

The description gives clear usage context by saying it is intentionally separate from analyze_stock so JSON analysis stays fast and light. It does not state exclusions or explicitly compare the tool with the individual get_* chart tools, but the primary alternative is named.

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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description discloses pricing, x402 payment mechanics, cache behavior for refresh and force_images, and concurrent execution. It does not discuss latency, failure modes, or quota exhaustion behavior, but the added context is substantial given the annotations already establish the safety profile.

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?

It is front-loaded with the report definition and then structured with clear Args documentation. There is minor redundancy, such as repeating the signed-in versus anonymous payment model across two paragraphs, but it remains readable and every section 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 no output schema, the description fully defines the return: it enumerates the report contents (direction, direction score, bullish/bearish factors, source-tool status, five chart embeds) and states that markdown is returned for display with the same data mirrored in structured JSON. Combined with payment and cache semantics, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 0%, so the description carries the full burden and does well: it gives a concrete symbol example and explains that refresh bypasses the backend's fresh IV cache for IV-driven modules, while force_images forces a fresh render instead of reusing the image cache. These explanations add real semantics the bare schema titles do not provide.

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

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

The description states a specific verb and resource ('Full markdown research report with five stock-report charts') and precisely defines the composite behavior — it runs analyze_stock and image generation concurrently and renders a presentation-ready report. It distinguishes itself from siblings like analyze_stock and generate_stock_images by making clear it is the aggregated report product.

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 clearly establishes the usage context: signed-in users call it within plan limits, while anonymous agents pay per call via x402. By stating it runs analyze_stock and image generation internally, it implicitly signals that callers should use this instead of assembling those tools themselves. It stops short of explicit when-not-to-use guidance (e.g., 'use analyze_stock for a quick single analysis').

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 non-destructive; the description adds value beyond that by disclosing the research-only disclaimer, per-plan quota/rate-limit behavior, and the three output signals. It stops short of 5 only because it doesn't say how much history/latency to expect or how stale the prediction may be.

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-loads what the tool returns, then availability/limits, then the argument — a sensible order with no filler. The Args block is slightly redundant with the schema but is short enough not to waste space.

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

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

With no output schema, the description correctly takes on the job of explaining the three returned signals, and it also covers plan eligibility, rate limits, and the non-advisory disclaimer. An agent has everything needed to call it and to interpret the result.

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% (ticker has no description in the schema), so the description must carry the load, and it does: it names the parameter, states 'Stock symbol', and gives a concrete example ("TSLA"). Missing format details (exchange suffix, case sensitivity, unsupported symbols) keep it from a 5.

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 — an AI next-day direction prediction for a ticker — and enumerates exactly what the answer contains (UP probability, buy/watch/sell lean, model consensus). It is clearly distinct from siblings like get_monte_carlo or get_equity_curve in substance, but never names a sibling to contrast with, so it stops 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?

Implies when to use it (next-day directional forecast) and warns 'research only, not a trade instruction', plus states plan availability and rate-limit exposure. However, there is no explicit guidance on how it differs in use from analyze_stock or get_monte_carlo — the agent must infer which forecasting tool to pick.

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

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

The annotations already establish that this is a read-only, idempotent, non-destructive, open-world operation. The description adds useful behavioral context beyond the annotations by stating plan availability and that requests are subject to per-day and per-minute rate limits.

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

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

The description is front-loaded with the core purpose and returned metrics, then adds plan limits and argument guidance without excessive text. The Args block is slightly formal but still efficient for a one-parameter tool.

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

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

For a simple read-only tool with one optional parameter, rich annotations, and no output schema, the description supplies the needed context: what is computed, which metrics are returned, who can use it, rate-limit caveats, and how ticker affects the result. Nothing essential for correct invocation appears to be 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 description coverage is 0%, so the description must carry parameter meaning for the single optional ticker argument. It does this well by explaining that ticker can isolate one symbol, giving an example like "SPY", and stating that leaving it blank returns all rows.

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 action and resource: backtesting quant strategy performance across a watchlist. It also names the returned metrics, making the tool's output purpose clear. It does not explicitly distinguish itself from sibling analysis tools such as get_monte_carlo or get_ai_prediction, 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?

Usage is implied by the backtesting purpose, and the ticker argument explanation clarifies how to get one row versus all rows. However, it gives no explicit guidance on when to choose this tool over related siblings like get_monte_carlo or analyze_stock.

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 genuinely new behavioral context: an access requirement ('available to all signed-in users') and the existence of a backend IV cache that refresh bypasses. It does not describe the shape or size of the returned IV structure, which is a minor remaining gap.

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

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

The purpose statement is front-loaded in the first sentence, followed by an access note and a compact Args block. Every line earns its place; the parenthetical glosses on calls/puts are slight redundancy but aid interpretation of 'upside' versus 'downside' skew.

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 two-parameter read-only analytics tool with no output schema, the description covers what the tool tells you conceptually, who can call it, and what the cache flag does. The main missing element is any indication of the response structure (e.g., whether it returns a term-structure table, rank/percentile, skew deltas), which would help an agent decide whether one call suffices.

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 full burden and largely meets it: ticker is given a concrete example format, and refresh is explained both as intent (bypass the cache, pull the latest option chain) and default (False). Adding cost or latency implications of forcing a fresh chain pull would push this higher.

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 and analytic dimension: implied-volatility structure for a stock, covering expensiveness, volatility squeeze, and call/put skew. That is far more than a restatement of the name. It stops short of distinguishing itself from the closest sibling, get_option_pressure, so an agent must infer the 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?

Usage is implied by the questions the tool answers ('how expensive options are', 'paying up for upside'), which suggests when to reach for it. But there is no explicit when-to-use or when-not-to-use guidance, and no routing away from get_option_pressure or analyze_stock, which likely overlap. The only explicit conditional content is the refresh/ cache note.

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 genuinely new behavioral context: the method (thousands of random paths), the ~10 trading day horizon, and the two outputs it estimates. It stops short of noting that results are stochastic or whether the simulation repeats identically across calls.

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 delivers purpose, method, horizon, and return content, followed by a single-line argument note. Nothing is padded or buried.

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

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

There is no output schema, so the description bears the burden of explaining results; it names the estimates (range, probability of gain) but not their shape, units, confidence level, or the volatility assumptions behind the paths. Adequate to call correctly, thin for interpreting what comes back.

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 schema only labels the field 'Ticker', so the description's 'Stock symbol, e.g. "AAPL"' is the sole source of format guidance and it supplies a concrete example. With a single required string parameter that is sufficient semantics, though it omits exchange or suffix conventions.

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 technique and resource — Monte Carlo price simulation over the next ~10 trading days — and says what it produces (a likely price range and the odds of finishing higher). That is enough to separate it from siblings like analyze_stock or get_ai_prediction in kind, though it never explicitly contrasts itself 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?

Usage is only implied: the ~10-day horizon hints at short-term probabilistic queries, but there is no statement of when to pick this over get_ai_prediction or get_iv_radar, and no prerequisites or exclusions. An agent must infer the selection rule from the tool's name and sibling names.

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, non-destructive and openWorld, so safety is covered. The description adds value by disclosing what is computed, but omits important behavior: how the expiry is selected when both weekly and monthly are available, data freshness, and whether an invalid ticker yields an error or an empty map.

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 core sentence is front-loaded and every clause names a returned metric, so nothing is wasted. The Python-docstring 'Args:' block is slightly awkward for a tool description but is short and harmless.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating the four metrics. For a single-parameter read-only tool, only the expiry-selection rule and failure behavior are missing, which is a modest gap.

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

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

One required parameter with 0% schema description coverage, so the description must compensate. It does only minimally by restating 'Stock symbol, e.g. "SPY"', which adds an example format but no constraints on exchange suffix, case, or support for index/ETF 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?

Names a specific resource (option-chain pressure map) and enumerates the concrete outputs — Max Pain, dealer Gamma Wall, weekly high, squeeze target — so an agent knows exactly what it returns. It doesn't explicitly differentiate itself from the closest sibling, get_iv_radar, which also deals with options-derived metrics, so it stops 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?

No statement of when to use this versus alternatives such as get_iv_radar or analyze_stock, and no prerequisites or exclusions. The only usage signal is the implied scope of 'nearest weekly/monthly expiry', which is a scope constraint rather than guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety behavior is covered. The description adds important behavioral context: it is a paid Pro tool, priced per call, with Credits for signed-in users and x402 USDC payment for anonymous callers.

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

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

The description is front-loaded with the core purpose and then explains payment/auth handling before the argument. The payment details are somewhat verbose but relevant to correct invocation, and the overall structure is easy to scan.

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 one documented parameter, rich annotations, and an output schema, the description covers the main gaps an agent needs to call the tool correctly. The main missing element is sibling differentiation, which is more of a usage-guideline gap than a completeness gap.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning. It does so adequately for the single parameter by stating 'symbol: Stock symbol, e.g. "NVDA"', giving both semantic meaning and an example.

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 resource and output: a full pre-trade risk scan JSON for a stock. It is clear what the tool does, but it does not distinguish itself from siblings such as analyze_stock, get_monte_carlo, or get_ai_prediction.

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

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

The description gives practical invocation guidance around payment and authentication modes, and 'pre-trade risk scan' implies a use context. However, it never states when to choose this tool over sibling analysis tools or when not to use it.

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

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

Goes well beyond the annotations: discloses that no password/wallet/browser is needed, that the account is bound server-side so subsequent calls are metered as the caller, that the account starts unverified with a capped evaluation allowance, that confirming email grants a one-time 100-Credit 14-day trial, and that re-calling returns the same account with a fresh key while another owner's address is refused. The 'fresh key on repeat' behavior is consistent with idempotentHint=false rather than contradicting it.

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

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

Front-loaded with the action and outcome, then progressively discloses usage triggers, prerequisites, and account lifecycle. It is longer than typical but nearly every sentence carries operational weight; only the trailing Args block lightly restates the email requirement already covered above.

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

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

No output schema exists, yet the description still tells the agent what comes back (an API key, same account with a fresh key on repeat) and what happens after registration (verification email, credit grant). For a single-parameter, unauthenticated bootstrap tool, nothing an agent needs to call it safely 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 description coverage is 0%, so the description must carry the meaning, and it does: the email is 'the real user email address that will receive verification', must not be empty or fabricated, and must be obtained from the user before calling. That is more semantic guidance than the bare `format: email` schema provides.

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

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

States a specific verb and resource ('Register a free hpsilab account') plus the immediate outcome ('receive an API key immediately'). It also distinguishes itself from all siblings by declaring it is 'the only tool that works without an API key', which explains why it sits alongside market-analysis tools.

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

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

Gives explicit triggers (user has no API key and asks to sign up, or a refusal's next_actions names register_account and the user agrees) and an explicit prohibition (do not call with an empty or fabricated email; ask the user first if unavailable). Both the when and the when-not are covered with no inference required.

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