stock-signal-us

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

With no annotations, the description carries the full burden and covers it thoroughly: grading thresholds, score range, snapshot nature, informational-only status, payment requirements, and the by-design neutral band. It also discloses the per-timeframe breakdown, so an agent knows exactly what to expect in the response.

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 long but densely packed with necessary information. It front-loads the core purpose, then grading, then payment, then sibling contrast. Every sentence adds functional value, though it could be slightly more condensed without losing essential details.

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?

Despite being a paid tool with no output schema, the description fully covers return values (zone, score, per-timeframe breakdown), grading logic, payment flow, and the difference from pitch. There is nothing an agent needs to know to call it correctly that is omitted.

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% (symbol with description). The description adds value beyond the schema: it specifies the covered universe (S&P500 + major indexes), gives examples including indices with caret, and explains how the symbol maps to the output. This enriches meaning without redundancy.

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 ('Return') with a clear resource ('bottom/top verdict') and scope ('one US stock or index/ETF'), and explicitly contrasts with sibling pitch to differentiate. Includes concrete examples and universe coverage, so an agent knows exactly what this tool does and what it does not.

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 clear guidance: use this for any covered symbol versus the free pitch which is showcase-only. Mentions payment and retry on 402, implying when to invoke. However, it does not explicitly contrast with scan_bottoms/scan_tops (which likely scan multiple symbols), but the single-symbol mention makes that implicit.

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?

With no annotations, the description carries the burden but fails to disclose side effects, expected outputs, or the interactive/stateful nature of the funnel. Phrases like 'phases' and 'free' imply a guided flow but do not specify what happens on each invocation or whether it modifies user state.

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 somewhat redundant with 'FREE and OPTIONAL' and 'you may skip it' both included. It could be tightened while preserving the phase list and the caveat about skipping, making it more direct.

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 multi-phase interactive nature implied by the tool, the description lacks essential details about each phase's behavior, expected inputs per phase, and return values. It also does not clarify how this tool relates to siblings like 'rate' or how one would transition between phases, leaving significant gaps for an agent to act 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 schema defines three parameters and the description adds meaning to 'symbol' (free sample only for NVDA, otherwise delegates to paid evaluate_symbol). However, 'phase' and 'interest' are not elaborated beyond their enum/boolean types, and the description repeats the schema's enum values without deeper explanation.

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 this is an intro and subscription funnel for the US-stock signal agent, listing the phases. It also clarifies that it can be skipped in favor of other tools, giving a clear sense of its high-level purpose.

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 says the tool is optional and can be skipped for evaluate_symbol, scan_bottoms, or scan_tops, which helps with when not to use it. However, it does not explain when a user would want to use this funnel versus the rating tool or when each phase is appropriate.

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?

No annotations, so description carries burden. Discloses free nature and no payment, but omits side effects or confirmation. Adequate for simple input.

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?

Single, well-structured sentence with key info front-loaded. 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?

Completeness is good for a simple feedback tool: explains purpose, parameters, usage context. Lacks return value info but acceptable without output schema.

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?

With 0% schema description coverage, description adds meaning: score range 1-10, pros/cons as text. However, doesn't mention that score is required while others optional.

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?

Clearly states it's a feedback/rating tool for after trading on signals. Distinguishes from sibling tools like evaluate_symbol or scan_* by focusing on user-submitted rating.

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 context ('after trading on our signals') but no explicit when-not-to-use or alternative tools. Lacks exclusions.

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?

With no annotations provided, the description takes on the full burden and does solid work: it discloses the $0.01 per-call payment via x402, the 402 challenge, the PAYMENT-SIGNATURE header retry, and states no account/signup/commitment. It slightly lacks details like rate limits or a sample of the returned shape, but the key external-behavior risks are covered.

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?

Purpose is front-loaded, and the payment/retry instructions are concise though dense. Minor redundancy and marketing-like phrases such as 'BEST COLD START' slightly dilute the structure, but the content is otherwise efficient and readable.

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?

One parameter, no output schema, and no annotations. The description covers the essential operational caveats (pricing, retry, cold-start) and the result type. It doesn't specify exactly how the ranked stocks are represented (ticker vs. name), but for a simple list tool this is complete enough to enable a successful call.

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% for the single `limit` parameter, though the description itself adds no field-level semantics beyond the schema. At baseline, because the schema says it all, no further explanation is required.

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: scan the US market snapshot (S&P500 + majors) and return stocks at a bottom, ranked most-bottom first. It also sets itself apart from the sibling `pitch` tool by saying pitch reports the count while this one names the stocks.

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?

Clear usage context: it marks itself as the best cold-start tool because no symbol selection is needed, and explicitly contrasts with the free `pitch` tool which only tells how many stocks are at a bottom. It stops short of giving explicit when-not-to-use or alternative selections for `scan_tops` or `evaluate_symbol`, but the intended use is well framed.

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?

No annotations exist, so the description carries the full disclosure burden. It handles this well by surfacing the payment requirement ($0.01 via x402), the no-account policy, and the retry-with-PAYMENT-SIGNATURE-header behavior on the 402 challenge — exactly the operational traits an agent must know. It also discloses the ranking behavior. Lacks rate-limit or result-shape detail, but the critical behavioral surface is covered.

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?

Purpose is front-loaded in the first sentence. The payment block, cold-start note, and pitch comparison each earn their place and are ordered sensibly. Slightly dense with the payment details mid-description, but nothing is wasted or 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?

For a paid, ranked-list tool with no output schema, it covers the essential ground: operation, ranking order, payment mechanics, 402 retry flow, cold-start suitability, and sibling differentiation. It does not spell out the per-result return format beyond 'names them', a minor gap given the tool's breadth.

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% — the single `limit` parameter is fully documented in the input schema ('How many to return (default 5, max 50)'). Per the baseline rule for high coverage, 3 is appropriate; the description adds no parameter-specific 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 a specific verb+resource ('Scan the US market snapshot and return stocks currently at a top (sell), ranked most-top first'). The 'top (sell)' phrasing plus the sibling name scan_bottoms makes the orientation unambiguous, and the cold-start note ('you do not need to pick a symbol') separates it from symbol-specific tools like evaluate_symbol.

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 clear usage context: the BEST COLD START framing tells the agent this is the entry-point tool for whole-universe scans, and it explicitly contrasts with pitch ('tells you HOW MANY... this names them'). It does not explicitly say when NOT to use scan_bottoms, but the top/bottom contrast is strongly implied. No explicit exclusions, so not a 5.

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