stock-signal-us

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

No annotations provided, so description carries full burden. It discloses snapshot nature and informational purpose, but does not detail potential side effects or permissions needed, which are minimal for a read-only query.

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

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

Two sentences efficiently communicate purpose, input format, output range, and data source. No redundant or filler content.

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 tool with one parameter and no output schema, the description sufficiently covers purpose, input requirements, output format, and data freshness. The agent has all needed information to use 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% for the single parameter, but description adds value with concrete examples (NVDA, AAPL, ^IXIC) and clarifies acceptable indices. This goes beyond the schema's basic description.

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?

Description clearly states the tool returns a bottom/top verdict for a single US stock or index/ETF, using specific verbs like 'Return' and resources. It distinguishes from siblings by focusing on individual symbols rather than scanning lists.

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 when to use (to get a verdict for one symbol) and provides output details (zone and score). While explicit when-not or alternatives are absent, the sibling tools offer context for differentiation.

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 provided, so description carries full burden. It mentions the tool is free and no payment, but does not disclose statefulness, side effects, or idempotency. The phases imply state progression, but the description does not clarify whether calling pitch again after completion is allowed or what happens. Some behavioral context is provided via the interest parameter for opting out, but overall transparency is moderate.

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?

Description is extremely concise: two sentences plus a phase list. Front-loaded with the critical instruction 'START HERE — your first call to this agent MUST be pitch'. Each phrase (free, no payment, phases, interest:false to bow out) earns its place without redundancy.

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 no output schema and no annotations, the description covers the essential context: tool purpose, mandatory first-call rule, phase sequence, and exit condition. It lacks details on return values, error handling, or state management after phases, but for a conversational introduction tool, it is reasonably complete. The presence of sibling tools (evaluate_symbol, rate, etc.) suggests the agent can infer alternatives.

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 only 33% (only symbol documented). Description adds meaning: for 'interest', it says 'Pass interest:false to bow out', clarifying its role as an exit gate. For 'phase', the description lists all enum values in context (hello, value, catalog, sample, subscribe), adding structure beyond the schema. The symbol's schema description already covers its use in the sample phase. The description significantly compensates for the low schema coverage.

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?

Description clearly states the tool is for the intro and subscription funnel of a US-stock signal agent, with a specific verb ('pitch') and resource ('subscription funnel'). The phrase 'START HERE' and the list of phases (hello, value, catalog, sample, subscribe) differentiate it from sibling tools (evaluate_symbol, rate, scan_bottoms, scan_tops) 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?

Explicitly states 'your first call to this agent MUST be pitch (free, no payment)', providing a mandatory usage condition. Also mentions passing interest:false to bow out, giving a clear exit strategy. The phase enumeration guides the expected conversational flow, implicitly telling when to use each phase.

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 full burden. It discloses that the tool is free and requires no payment, but does not mention side effects (e.g., creating a record), rate limits, or whether ratings are anonymous. The mutation nature is implied but not explicit.

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, well-structured sentence with a dash separating purpose and details. No filler; every word adds value. Front-loaded with 'FREE feedback 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 feedback tool with 3 parameters and no output schema, the description covers major aspects: purpose, usage context, parameter meanings, and cost. Missing details like return value or error conditions are minor given the tool's simplicity.

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%, but the description adds meaning by specifying 'score 1-10' and 'pros and cons', mapping directly to the three parameters. It provides context beyond type information, though it lacks constraints like length limits.

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 verb ('leave a rating'), the resource ('our signals'), and the scope ('score 1-10 plus pros and cons'). It effectively distinguishes from sibling tools by specifying it's a feedback tool after trading, unlike 'evaluate_symbol' or 'scan' 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 provides clear context for use ('after trading on our signals') and mentions a key condition ('No payment needed'). However, it does not explicitly tell agents when not to use this tool or point to alternatives among siblings, though the context strongly implies 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool scans a market snapshot and returns ranked results. It does not mention destructive actions or authentication needs, but the read-only nature is implied. The ranking order is a useful behavioral detail.

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 sentence that front-loads the action and scope. Every word is necessary and contributes to understanding. No wasted text.

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 has one parameter, no output schema, and no annotations, the description is fairly complete. It explains what the tool does and the ranking. However, it does not specify the output format (e.g., just symbols or with scores), which could be helpful but is not critical for a simple scan.

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% with a clear description of the 'limit' parameter. The tool's description adds context about ranking but does not add significant meaning beyond the schema. 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 clearly states the tool scans the US market snapshot (S&P500 + majors) and returns stocks at a bottom, ranked most-bottom first. It is specific about the resource and action, and distinguishes from the sibling tool scan_tops by focusing on bottoms.

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 context is clear: use this tool to find buying opportunities (stocks at bottom). The sibling scan_tops implies the opposite use case. However, explicit when-to-use or when-not-to-use guidance is lacking, but the purpose is evident.

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 are provided, so the description carries full burden. It describes a read operation but does not disclose whether it requires authentication, rate limits, data freshness, or any side effects. It lacks explicit safety guarantees.

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, front-loaded sentence with no extraneous words. Every part earns its place: action, scope, output ranking.

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 and no annotations, the description omits the structure of the returned data (e.g., fields included) and error or edge-case behavior. For a simple scanning tool, more context is needed for an agent to handle responses 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% for the single parameter 'limit'. The description adds no additional meaning beyond 'How many to return (default 5, max 50)' already present in the schema. Baseline score of 3 applies.

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 uses a specific verb 'scan' and resource 'US market snapshot', clearly stating the tool returns stocks at a top (sell) ranked by most-top first. It distinguishes from sibling tool 'scan_bottoms' which does the opposite.

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 the tool is for identifying sell signals through the phrase 'stocks currently at a top (sell)', but does not explicitly state when to use it over alternatives like 'scan_bottoms' or mention prerequisites or exclusions.

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