StockLens

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the description doesn't need to restate those. It adds useful behavioral context: plan capacity limits, the result states the limit, and the tool does not execute trades or record holdings/transactions. It also clarifies the one-ticker-per-call constraint, which is beyond the schema's pattern. Minor gap: it doesn't describe the exact success/error response shape, but the output schema exists and the description covers the key behavioral traits.

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 three sentences, front-loads the core action and purpose, and every sentence earns its place. The capacity/plan note and the explicit exclusions are valuable and not redundant with the schema or annotations. No wasted words.

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

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

Given the tool's simplicity (2 params, 1 required, output schema present, no nested objects), the description is nearly complete. It covers the action, scope, plan limits, and exclusions. The only minor gap is that it doesn't explicitly state what a successful response contains, but the output schema exists and the description's behavioral notes are sufficient for an agent 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 description coverage is 100%, so the schema already documents both parameters. The description adds value by reinforcing that exactly one ticker per call is allowed and that the exchange is optional and resolved automatically if omitted. It doesn't add much beyond the schema, but the baseline for high coverage is 3, and the description's explicit one-ticker constraint and exchange-resolution note push it to a 4.

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 ('Add'), a specific resource ('one stock ticker to the authenticated user's StockLens watchlist'), and the purpose ('tracked and scored going forward'). It also clearly distinguishes itself from sibling tools by explicitly saying it does NOT execute trades, record a holding/transaction, or accept more than one ticker per call.

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 context on when to use this tool (adding a ticker to a watchlist) and explicitly excludes related actions (trades, holdings, transactions). It also mentions plan capacity limits and directs users to stocklens.com for plan changes. However, it does not explicitly name sibling alternatives like remove_from_watchlist or discover_stocks, so the when-not-to-use guidance is implied rather than fully explicit.

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 and destructiveHint=false, but the description adds crucial behavior beyond that: it explicitly states the tool does NOT execute trades or give personalized recommendations, and discloses plan-dependent behaviors (free accounts get locked results with zero stocks when sorting by score, with a plan message to relay verbatim). It also promises not to return more stocks than the structured result contains, which is extra safety context.

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?

Although longer than average, every sentence earns its place: the purpose is front-loaded, the alternatives and exclusions are stated early, and plan behaviors are packed efficiently. There is no fluff, redundancy, or tangential information, and the structure flows logically from purpose to constraints.

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

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

Given 11 parameters, 4 enums, plan differences, and a locked-result edge case, the description covers all essential operational details. It explains the reach caps, the free-account locked behavior, and explicitly rules out trade execution and personalized advice. The output schema exists, so return value explanation is unnecessary. Nothing an agent needs to call 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 description coverage is 100%, so the baseline is 3. The tool description does not add new semantics beyond what the schema already documents; it only paraphrases the filtering and sorting capabilities. No additional format, syntax, or edge-case details are provided, so it does not elevate beyond the baseline.

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

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

The description states a specific verb ('Screen'), a resource ('StockLens nightly-analyzed universe'), and a precise scope (filtering by region/exchange/sector/etc., sorting, and returning top/bottom N). It also differentiates itself from siblings by explicitly naming get_market_summary and stating it is the only ranking/comparison tool. This makes it immediately distinguishable from alternatives.

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

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

Explicitly states when to use it ('any top N, best/worst, highest/lowest scored, or filtered market-wide request') and when not to (never fabricate from get_market_summary or general knowledge). It also provides plan-specific usage constraints (free vs Pro/Max reach limits) and the locked-result behavior for free accounts sorting by score.

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, and destructiveHint=false. The description adds valuable behavioral context: it does not wait for completion, returns the current state once, and explains what complete results include. This goes beyond the annotations and clarifies the non-blocking, one-shot nature of the call.

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

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

The description is well-structured and front-loaded with the core purpose, then details about statuses, retry behavior, and exclusions. It is slightly longer than necessary but every sentence adds functional value, and the logical flow is clear.

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

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

Given the tool's complexity, the description covers all essential aspects: status values, progress, retry timing, complete result contents, and explicit exclusions. The presence of an output schema means return format details are not needed, and the description fully equips an agent to call it correctly.

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

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

Schema coverage is 100%, so the parameter analysis_id is fully described in the schema. The description reiterates that it must come from initiate_analysis and that no ticker is accepted, but this does not add substantial semantic value beyond the schema. Baseline of 3 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 clearly states the tool fetches the result or progress of a previously initiated StockLens analysis, using a specific verb and resource. It explicitly distinguishes itself from siblings by stating it does NOT start a new analysis, does NOT rank or screen stocks, and does NOT accept a ticker, which makes it unambiguous among the sibling 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?

It provides explicit when-to-use guidance: after initiate_analysis, and when-not-to-use: for multi-stock lists use discover_stocks, and it clarifies that it only accepts analysis_id. It also gives retry guidance with retry_after_seconds and advises checking again only if the user asks to continue, leaving no ambiguity.

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 mark readOnlyHint and idempotentHint, and the description adds meaningful behavioral context: tier-based access, the TIER_INSUFFICIENT error semantics ('NOT a statement that the stock is unscored'), the nightly data derivation, and the instruction not to tell users a stock is unscored. This goes well beyond the structured annotations.

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

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

The description is detailed but every sentence contributes: return payload, access tiers, error semantics, use case, and exclusions. It front-loads the core purpose and the key constraints before moving to edge cases, with no filler or repetition.

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

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

Given the output schema exists and annotations cover safety, the description fills the remaining gaps: when to call it, what tier restrictions apply, how to interpret TIER_INSUFFICIENT, and which sibling to use for multi-stock queries. An agent has everything needed to invoke it correctly and avoid common mistakes.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds value by explicitly constraining input to a single ticker and clarifying that exchange is optional and auto-resolved. It also reinforces that the tool cannot accept multi-ticker or ranking-style input, which is useful parameter-level guidance beyond the schema.

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

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

The description opens with a specific verb and resource: 'Retrieve the latest StockLens composite analysis summary for a stock ticker.' It also distinguishes this tool from siblings by explicitly stating it does NOT rank, sort, filter, or list multiple stocks, and points to discover_stocks for those cases.

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 use case: 'Use this to quickly assess a stock before deciding whether to run a full analysis.' It also provides clear exclusions: any 'top N', 'best/worst', 'highest/lowest scored', or filtered multi-stock request should call discover_stocks instead, and repeated calls to assemble a ranking are forbidden.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond that: plan-based capacity limits (Free up to 10 stocks, Pro/Max unlimited) and the fact that scores/grades may be absent when no completed score exists. These are useful behavioral details not in the annotations.

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

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

The description is two sentences with zero wasted words. It front-loads the core purpose, then packs in capacity limits, missing-data behavior, and a sibling reference, all in a compact, scannable format.

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 tool with no parameters, clear read-only annotations, and an output schema (which presumably describes the returned data), the description fully covers what it returns, plan constraints, and exclusions, leaving no gaps for an agent to call it correctly.

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

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

The tool has zero parameters, so per guidelines the baseline is 4. The description adds no parameter-specific info (none needed) and correctly states it accepts no ticker/filter arguments, which clarifies the lack of parameters.

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 ('Retrieve'), resource ('StockLens analysis summaries for the authenticated user's watchlist'), and clearly distinguishes itself from siblings by explicitly excluding ticker/filter arguments and market-wide ranking, pointing to discover_stocks for that. This makes the tool's unique purpose unmistakable.

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 explicitly says when to use it ('to give users an overview of their portfolio's analytical health') and when not to (does NOT rank/screen outside watchlist) and names the alternative (discover_stocks). This is exactly the when/when-not guidance an agent needs.

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

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

Annotations already signal destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate mutation. It adds critical context: credit consumption, asynchronous completion, reuse behavior, concurrent handling, and what the receipt reports. It goes beyond the annotation by explaining that credit charge may not be complete and that identical initiations get retry guidance, which is valuable for an agent managing side effects.

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 dense and comprehensive, which is appropriate for a complex tool, but it could be tightened. It front-loads the core purpose and async behavior, then covers exclusions and plan details. Some redundancy exists (e.g., credit mentions appear multiple times), and the length might reduce scannability, but every sentence contributes to avoiding misuse.

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

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

Given the tool's complexity (7 params, credit implications, async flow, plan variations), the description covers all critical aspects: what returns immediately, how to get results, reuse and concurrency, plan differences, and what it does not do. Combined with the detailed schema and output schema, an agent has enough to call it correctly. Minor gaps: it doesn't specify typical analysis_id format or timeout expectations, but these are less critical given the guidance to fetch results separately.

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 covers 100% of parameters with rich descriptions including enums, defaults, and alignment rules (e.g., risk_tolerance and analysis_emphasis). The description adds meaningful context beyond the schema: it clarifies that time_range is not a price forecast, that analysis_emphasis mismatches are rejected before credit consumption, and that evidence_history_family doesn't select a range on its own. These additions earn a 3, but since the schema already carries most of the semantic weight, the baseline of 3 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 clearly states the tool initiates a full StockLens AI analysis for a specific stock, with explicit scoping (single ticker) and immediate vs asynchronous behavior. It distinguishes itself from siblings by naming discover_stocks for multi-stock requests and fetch_analysis_result for retrieving results, so an agent knows exactly what this tool does and what it doesn't.

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 provides explicit when-to-use guidance (initiate analysis, retrieve results separately), when-not-to (does not screen, rank, compare, or trade), and names the alternative (discover_stocks for multi-stock, fetch_analysis_result for results). It also covers concurrency, credit consumption, and plan differences, leaving no ambiguity about selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the concrete behavioral fact that the tool returns 'pong', which the agent can expect and check. This goes beyond what annotations provide, justifying a score above baseline.

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?

A single, front-loaded sentence containing only essential information: purpose, return value, and use case. No padding, no redundancy. Every word contributes to an agent's ability to understand and invoke the 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 no-input, trivial-behavior tool with an output schema and safety annotations already present, the description provides everything needed to call it correctly. The agent knows what the tool doeshare and what to expect in response, leaving no critical gaps.

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

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

The tool takes zero parameters, so schema description coverage is 100% vacuously. There is nothing for the description to clarify about parameters. According to the baseline, 0 params earns a 4, and the description appropriately says nothing about inputs.

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 purpose: a health check that returns pong to verify MCP connectivity. It distinguishes the tool from all stock-analysis siblings, which serve entirely different functions. The resource ('MCP connectivity') and expected behavior ('returns pong') are clearly named.

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 clearly implies when to use the tool: whenever an agent needs to confirm MCP connectivity. It does not explicitly mention alternatives or exclusions, but the purpose is so distinct from sibling tools that no ambiguity exists. This meets the 'clear context' level, though not the 'explicit when-not/alternatives' bar.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds valuable behavioral context: the operation is destructive only to the watchlist entry, not to holdings/transactions, and it enforces one-ticker-per-call. This meaningfully exceeds annotation-only information.

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

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

Three sentences, each earning its place: primary action, critical exclusions/constraints, and cardinality. The most important scoping information is front-loaded and there is no filler.

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

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

For a two-parameter tool with a full schema, annotations, and an output schema present, the description is complete. It covers scope, authentication context, destructive limits, and the one-item constraint, so an agent has what it needs to call 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 description coverage is 100%, and the schema already documents ticker and exchange well, including the exchange-matching ambiguity behavior. The description reinforces the one-ticker rule but adds no new parameter meaning beyond what the schema already 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 the exact operation: 'Remove one stock ticker from the authenticated user's StockLens watchlist.' It distinguishes itself from adding, trading, and holding deletion, and explicitly clarifies scope and cardinality.

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 clear when-not-to-use guidance: does not execute trades, does not delete holdings or transactions, and cannot remove watchlist items with recorded transactions. It does not name a specific alternative tool for those cases, but the exclusions are explicit and actionable.

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