QuantApe Markets

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

Annotations include readOnlyHint: true, so the description doesn't need to repeat that this is a read-only operation. The description adds valuable context about rate limits and pricing (5/day anonymous, 10/day signed-in, 50/day power, $0.01 per call beyond), which is non-obvious and helps the agent anticipate costs and limits. It does not explain output structure (since no output schema is provided), but for a read-only list query, that's a minor gap given the annotation covers safety.

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, concise sentence that front-loads the core purpose ('Every stock screen a given ticker is currently in') and then includes critical usage constraints (pricing and rate limits) in a compact, readable way. No unnecessary words or repetition; every part adds value.

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 read-only tool with a single parameter and no output schema, the description is quite complete. It covers the tool's scope, rate limits, and pricing. The only missing detail is the exact output format (e.g., whether it returns list names, metadata, etc.), but given the simplicity and the fact that it's a listing operation, this gap is minor. It's not a complex tool requiring extensive context.

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 descriptions cover 100% of parameters: 'symbol' is described as 'Ticker symbol, e.g. NVDA or BRK-B.' The description doesn't add any new meaning to the parameter; it just confirms that the symbol is input to finding lists. Since the schema already covers the parameter adequately, 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's purpose: to find all stock screens (momentum, technical-signal, earnings, theme, thesis) that a given ticker is currently in. It names the specific resource (stock screens) and the action (find/list), and distinguishes it from sibling tools like list_smart_lists (which likely lists predefined lists) and get_smart_list (which gets details of a specific list). The phrase 'in one call' adds clarity about the comprehensive scope.

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 this tool: when you need all memberships of a ticker across different screen types. It provides clear context (one call vs. multiple calls) and even includes pricing tiers, which can guide usage (e.g., be aware of rate limits). However, it does not explicitly state when NOT to use it or mention alternatives (like get_smart_list for a single list's details).

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 readOnlyHint annotation already establishes safety, and the description adds useful behavioral detail by listing the returned metadata fields. 'Always free' adds context about access, and with no output schema, enumerating the return contents is valuable.

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 sentence that front-loads the core purpose, lists returned fields, and includes a cost-relevant note. There is 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?

For a single-parameter, read-only metadata tool, the description covers what the tool returns and the input source. It is mostly complete, though a bit more detail about the exact response shape or edge-case behavior would be ideal.

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%, with list_id already described as 'Screen id from list_smart_lists' and examples provided. The description does not add further parameter semantics beyond what the schema already supplies, so baseline 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 clearly states the tool returns metadata for one stock screen and enumerates the specific fields returned. It is clear about the resource and scope, but it does not explicitly differentiate itself from siblings like get_smart_list or list_smart_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 purpose implies when to use it: when metadata for a single screen is needed. However, it provides no explicit when-to-use versus alternatives or exclusions, so usage guidance is only implied.

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 readOnlyHint annotation, the description adds 'Descriptive, not a recommendation' and detailed cost/quota information (5/day anonymous, 10/day signed-in, 50/day power, $0.02 per call beyond). This is useful behavioral disclosure, though it doesn't detail response format or error behavior.

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 long but every sentence adds value: purpose, usage tip, pairing, non-recommendation disclaimer, and cost details. It is front-loaded with the core purpose and remains focused without 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?

For a tool with one optional parameter, no required input, and a read-only annotation, the description covers purpose, usage, behavior, cost, and pairing. Nothing essential is missing for an agent to decide and 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 sole parameter 'sections' is explained in the schema, but the description adds meaning by listing what each section contains (summary, fear_greed, sectors, rotation, news) and reiterates the 'pick fewer' guidance. This goes beyond the bare enum list in 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 clearly states that the tool provides 'Today's market conditions' with specific components: narrative, fear & greed index, sector scores, rotation, cycle phase, and news. This is a specific verb+resource and is easily distinguished from sibling tools about watchlists and smart 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 explicitly pairs the tool with get_my_watchlist for a specific use case, and advises picking sections to keep answers small. It provides clear context on when to use it, though it doesn't explicitly state 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?

Annotations already mark readOnlyHint=true; the description adds meaningful behavior beyond that: required Authorization Bearer token, 'Descriptive, not a recommendation', daily free allowances, and overage pricing via x402/USDC. This gives the agent useful expectations about auth and cost without contradicting the read-only hint.

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 dense sentence that leads with the core purpose, then covers auth, semantics, and quotas. The pricing detail is somewhat long but relevant and not wasteful. It 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 points to get_smart_list_metrics to imply the return shape and adds headlines. It also covers auth, quota, cost, and non-recommendation semantics. It could be more explicit about pagination response shape, but the reference to a sibling plus the parameter schema covers most 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?

Schema description coverage is 100%, so the input schema already documents limit, offset, and news_days thoroughly. The description adds no parameter-level detail beyond hinting at headlines, which is acceptable given the schema handles semantics.

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 identifies the operation: retrieving per-symbol metrics plus headlines for the caller's own watchlist. Differentiates from the sibling get_smart_list_metrics by scope ('your own watchlist') and by the added headlines, so an agent can distinguish it without opening the schema.

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 anchors usage by comparing to get_smart_list_metrics and adds the distinguishing 'plus the latest headlines, for your own watchlist'. It does not explicitly state when NOT to use it, but the comparison makes the intended context clear enough.

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 readOnlyHint=true annotation, the description discloses additional behavioral traits: it is 'Descriptive, not a recommendation,' it is paged with a 200-per-call maximum, and it includes specific free-allowance tiers plus overage pricing via x402. This adds meaningful operational and reliability 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?

The description is a single informative sentence that front-loads the core purpose and then expands with examples and cost details. Each element is relevant, though the pricing breakdown adds some length; it remains reasonably concise and well ordered.

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 three-parameter, read-only tool with no output schema, the description fully equips the agent: it explains what data is returned (symbols), that results are paged, and when extra cost may apply. It could add a bit more about the return shape or paging semantics, but nothing critical 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 necessary parameter information is already in the JSON schema. The main description adds example screen aliases such as 'golden-cross buy signals' (tying to list_id examples like golden_cross) and mentions paging, but does not materially extend the schema's own descriptions.

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: 'Symbols currently in a stock screen' with clear examples (today's earnings, golden-cross buy signals, AI beneficiaries). This distinguishes it from sibling tools like get_smart_list_changes, get_smart_list_metrics, and list_smart_lists by indicating it retrieves the current screen membership.

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 through phrasings like 'Symbols currently in a stock screen' and 'paged, max 200 per call,' but there is no explicit when-to-use vs. alternatives or exclusions. It does not name sibling tools or state when to prefer get_smart_list_changes or get_list_criteria.

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 the description adds valuable context beyond that: the baseline is 'last recorded' and can span several rebuilds, and usage is rate-limited with paid overage via x402. This gives the agent a clear picture of operational constraints and semantics.

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 main purpose is front-loaded, followed by useful examples and then quota/pricing details. It is slightly dense, especially the pricing clause, but every sentence contributes either to intent, context, or cost behavior.

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 single-parameter, read-only tool, the description gives enough context to invoke it: what it returns, what baseline means, and cost limits. It does not describe the exact output shape, but the 'which symbols entered or left' phrasing adequately conveys the return content.

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?

There is only one parameter, list_id, and its schema description is 100% complete ('Screen id from list_smart_lists whose additions and removals you want'). The tool description adds no extra parameter-level meaning, so the schema carries the full burden and the 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 clearly identifies what the tool returns: symbols that entered or left a stock screen since its last baseline, with concrete examples like golden crosses and momentum-leader removals. It does not use an explicit imperative verb like 'get' or 'list', and it does not name a sibling tool, but the 'entered or left' framing makes it distinct from get_smart_list and similar list-retrieval 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 when to use it: when you need membership changes since a baseline, such as new signals or dropped names. It offers examples but no explicit when-not-to-use guidance or direct comparison with alternatives like get_smart_list or get_smart_list_metrics.

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 provide readOnlyHint=true, and the description reinforces this with 'Descriptive, not a recommendation.' It adds meaningful behavioral context beyond the annotation: the free-tier quota (anonymous 5/day, signed-in 10/day, power 50/day), the $0.05 overage cost via x402, and the paging cap of 200. This is exactly the kind of cost/rate-limit context that helps an agent decide whether to call the tool.

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 dense sentence that front-loads the core purpose and metric list, then appends the paging and cost caveats. It is long but every clause earns its place: the metric enumeration is necessary for purpose clarity, and the quota/cost info is necessary for behavioral transparency. Slightly overstuffed, but well-ordered.

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 read-only, paged list tool with a fully documented schema, the description covers the essential context: what metrics are returned, paging behavior, cost/quota, and the source of list_id. There is no output schema, so the description's metric list partially compensates for the lack of a return-value schema. It doesn't describe the exact response shape, but the metric enumeration is sufficient for an agent to know what to expect.

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 all three parameters (list_id, limit, offset) with descriptions. The tool description adds the context that list_id comes from list_smart_lists and that paging is capped at 200, which slightly enriches the schema. Baseline 3 is appropriate because the schema carries 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 opens with a specific verb and resource: 'Per-symbol metrics for a stock screen,' then enumerates the exact metric families returned. It distinguishes itself from siblings like get_smart_list (the list itself) and get_smart_list_changes (changes over time) by stating it returns per-symbol metrics. The scope is unambiguous.

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 states the tool is for a stock screen and lists the metrics, which implies when to use it: when you need per-symbol detail for a screen. It also notes paging (max 200 per call) and the list_id source from list_smart_lists, which orients the agent. It does not explicitly name sibling alternatives or state when NOT to use it, but the context is clear enough.

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 the tool as read-only, so the description only needs to add extra behavioral context. It adds 'Always free' and notes that pricing/allowance data is returned, but it does not discuss pagination, limits, or other runtime behavior.

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 action, packs useful detail into each phrase, and avoids filler. The category list is long but directly helps an agent choose a category_id.

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 one-optional-parameter listing tool, the description is largely complete: it states what is returned, that it is free, and how to use it as an entry point. The lack of an output schema is mitigated by listing the returned fields, though exact response shape is not specified.

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's category list reinforces the category_id parameter with additional examples, but it doesn't clarify exact accepted values or format 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?

The description clearly identifies the resource (stock screens), the operation (browse by category), and the returned fields. It does not explicitly name sibling tools to differentiate against, though 'Start here to find a screen id' implies it is the catalog entry point.

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: use this tool as the starting point to find a screen id, and it is always free. It does not explicitly mention when not to use it or name alternatives like get_smart_list for retrieving a specific screen.

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