StockLens

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

Beyond the readOnly/idempotent annotations, the description discloses critical non-obvious behaviors: polling is non-blocking, each call returns the state exactly once, and the response shape varies by status (in_progress vs complete). It also details what complete results include (composite score, domain breakdowns, key insights, optional AI narrative). No contradiction with 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 compact and front-loaded: purpose first, then behavior, retry guidance, and result contents. Every sentence adds value without redundancy. The 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?

The description covers the tool's purpose, non-blocking behavior, retry guidance, and the content of both progress and complete responses. Since an output schema exists, it doesn't need to enumerate every field, but it gives enough context for an agent to understand what to expect and how to interact.

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

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

The single parameter (analysis_id) is fully described in the schema ('The analysis_id returned by initiate_analysis'), providing 100% coverage. The description doesn't add extra parameter meaning, but the schema already carries the necessary semantics, so baseline 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 starts with a specific verb ('Fetch') and a clear resource ('result or progress of a previously initiated StockLens analysis'), immediately distinguishing it from sibling tools like initiate_analysis and get_market_summary. It fully captures what the tool does.

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?

Provides explicit usage context: it explains that the tool returns the current state once, does not wait for completion, and includes a recommended retry interval (retry_after_seconds). It also tells the agent to check again only if the user asks to continue, which serves as a clear when-to-use and when-not-to-use guideline.

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, so safety is well-covered. The description adds value by disclosing 'No authentication required' and 'data is derived from most recent nightly analysis run' — useful behavioral context about data freshness and access requirements that annotations don't capture.

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 a compact 4-sentence block that front-loads the core purpose, lists key outputs, discloses data freshness and auth, and ends with a direct usage recommendation. Every sentence contributes value with no waste.

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?

The tool has a rich output schema and annotations, so structural details are covered elsewhere. The description provides the key remaining context: data source freshness (nightly run), no-auth requirement, and an explicit use case for quick assessment. Minor gap: it doesn't explain what 'full analysis' means or reference the sibling initiate_analysis directly, though the usage guidance implies this relationship.

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 (ticker and exchange) well. The description adds no new parameter-level detail, which is acceptable given the schema coverage. Baseline 3 is appropriate since the schema handles the parameter documentation burden.

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 retrieves a StockLens composite analysis summary with specific verb ('retrieve'), resource ('composite analysis summary'), and output details (composite score, rating, per-domain scores, strengths/challenges). This distinguishes it from siblings like get_portfolio_insights and initiate_analysis, which serve different purposes.

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 explicitly directs when to use this tool: 'Use this to quickly assess a stock before deciding whether to run a full analysis.' This creates a clear usage path and implies when NOT to use it (when a full/detailed analysis is needed). It also clarifies the data is from the most recent nightly run, setting expectations about freshness.

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, so safety profile is covered. The description adds useful context beyond annotations: tier-based limits (FREE returns up to 3 holdings), the possibility that values may be absent when no completed score exists, and that it targets the user's watchlist specifically. This is meaningful behavioral disclosure that complements the annotation set.

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, zero waste. Front-loads the primary purpose, covers edge cases (absent values), notes tier limits, and ends with a clear usage recommendation. Every sentence 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?

An output schema exists but has no nested objects, so the description reasonably handles the complexity of tier-dependent data. It covers the key variability (plan limits, absent scores) that a schema alone wouldn't convey. Could arguably note that without a completed score no data is returned for that stock, but it already says 'either value may be absent' which sufficiently telegraphs the 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?

Zero parameters exist, so the schema cannot carry any burden. The description compensates by explaining what is semantically returned (composite scores and grades, absent values, tier-dependent holdings count). With 0 params, baseline is 4, and the description earns it by clarifying the return semantics that vary by tier.

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?

Specific verb+resource ('Retrieve StockLens analysis summaries') with clear scope ('for the authenticated user's watchlist'). Explicitly states what it returns (composite scores and grades) and the tier-dependent behavior (FREE=3, PRO/MAX=full). Clearly distinguishes from siblings like initiate_analysis and fetch_analysis_result which do different jobs.

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?

States when to use it: 'Use this to give users an overview of their portfolio's analytical health.' It implies alternative tools exist for deeper operations (initiate_analysis, fetch_analysis_result), though it doesn't explicitly state when NOT to use this or name alternatives directly. Decent contextual guidance for how this fits among siblings.

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 description goes well beyond the annotations, disclosing asynchronous behavior, credit consumption (with the nuance that the receipt does not claim a charge has completed), reuse possibility, receipt fields (new_run_started, reused_existing), retry guidance for concurrent identical requests, and plan-based limitations (Free vs Pro/Max). This is rich behavioral context that the annotations (readOnlyHint=false, destructiveHint=true) do not 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?

The description is fairly long (around 150 words) and covers many aspects, but it is front-loaded with the primary purpose and then logically progresses through behavior, reuse, receipt, retry, and plan limitations. Every sentence adds substantive information; it is more detailed than a typical description but justified by the tool's complexity. It is not overly redundant.

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 (asynchronous, credit-consuming, potential reuse), the description covers all key aspects: immediate return of analysis_id, asynchronous completion, how to retrieve results (fetch_analysis_result), reuse behavior, receipt contents, retry guidance for concurrency, and plan-based depth restrictions. It also aligns with the output schema (analysis_id) without needing to repeat return details. The description is fully complete for an agent to select and invoke the tool 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 baseline is 3. The description adds value by clarifying plan restrictions: 'Free supports the standard Analysis only; Pro and Max unlock Plus Analysis.' This is not present in the schema for the depth parameter and gives practical guidance. The description also reinforces the asynchronous nature of credit consumption, but the schema already describes the credit roles. Overall, it adds enough extra meaning to warrant 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 begins with 'Initiate a full StockLens AI analysis for a specific stock,' which clearly states the verb (initiate), resource (analysis), and scope (specific stock). It differentiates from siblings by explicitly mentioning that results are retrieved via fetch_analysis_result, and other siblings (get_market_summary, get_portfolio_insights) are not about initiating per-stock analysis.

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 clear context: returns an analysis_id immediately, completion is asynchronous, and results are retrieved via fetch_analysis_result. It also notes that a recent matching analysis may be reused, which guides when initiation might avoid new work. However, it does not explicitly state 'when not to use' this tool beyond implying reuse, but the mention of fetch_analysis_result as the retrieval alternative is a strong usage signal.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the specific behavioral detail that it returns 'pong' as the response format, which provides concrete behavioral context about the return value beyond the annotations' 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?

The description is a single, efficient sentence with zero waste. Every word earns its place - it states the purpose ('Health check'), the output ('pong'), and the purpose ('verify MCP connectivity') in a highly compact 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 zero-parameter health check tool with an output schema, the description is reasonably complete. The only minor gap is that the description doesn't detail what the output schema contains, but since an output schema exists, that burden shifts away from the description. The description adequately covers a simple tool's needs.

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, and the schema coverage is 100% (there is nothing to describe). With 0 params, the baseline is 4 per the rubric. The description correctly doesn't fabricate parameter information that doesn't exist.

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 performs a health check returning 'pong' to verify MCP connectivity, which is a specific verb+resource. It doesn't explicitly distinguish from siblings, but the tool's purpose is inherently distinct given it's a connectivity check versus the analytical 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?

The description implies usage context (verifying connectivity), which is reasonably clear for a health check tool. However, there's no explicit when-when-not guidance or mention of alternatives, though the utility of a ping in a toolset of analytical tools is largely self-evident.

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