QuantApe Markets

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

With only readOnlyHint=true in annotations, the description carries the rest and does so richly: it discloses the per-day allowance tiers (5/10/50), the $0.03 x402 overage, that the digest adds latency but not cost, and that a failed digest returns digest: null with digest_status rather than an error. These are exactly the behavioral traits annotations cannot express.

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?

It is front-loaded correctly, but it is a single dense wall of text that sprawls well past the point of necessity. Much of the field-level explanation (move.raw_*, residual_*, peers.corr, peers.kind) duplicates the output schema, which already exists, so those sentences do not fully earn their 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?

For a read-only analytics tool with a rich output schema, it covers everything an agent needs: inputs, mode semantics, cost/allowance, latency, and digest failure handling. Nothing required to call it 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains what days (5 vs 20 sessions) means, what mode='peers' changes about the output, and the symbol/cluster_id mutual exclusivity. It goes modestly beyond the schema rather than merely restating it.

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+resource: it returns what recently happened to a ticker's peers — cluster moves (raw/market/residual), news, earnings reactions, guidance, movers and themes. It distinguishes itself from siblings by explicitly pointing to graph_neighbors as the source of cluster_id, so an agent can tell it apart from get_stock_insights or graph_neighbors 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?

It clearly states input routing (give a symbol or a cluster_id from graph_neighbors, not both), explains the cluster vs peers mode selection, and notes the fallback for mega-caps without a tight cluster. It stops short of explicitly contrasting when to prefer this over siblings like get_stock_insights, but the operational context is strong.

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 only provide readOnlyHint=true, and the description does not contradict that. It adds useful behavioral context: daily free quotas for anonymous, signed-in, and power users, plus the paid x402/USDC path beyond the limit. It does not cover empty-result or error behavior, but the output schema and readOnly annotation lessen that gap.

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 purpose is front-loaded in the first sentence, and the second sentence packs quota and pricing information compactly. The quota detail is relevant but somewhat dense; still, there is no filler or 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?

For a tool with one required parameter, a fully documented schema, an output schema, and a readOnly annotation, the description provides enough information to call it correctly. It explains the purpose, enumerates membership categories, and covers quota/payment behavior, so 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 coverage is 100% and the input schema already documents the single `symbol` parameter with an example. The description adds only the phrase 'given ticker' and no additional format, case, or usage nuance beyond the schema, so the 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 identifies the tool's purpose: return all stock-screen memberships for a given ticker, including momentum, technical, earnings, theme, and thesis lists. It is specific about the resource and scope, though it never explicitly names a sibling tool or uses an explicit verb like 'find' or 'list'.

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 intended use is implied: when an agent needs every screen a ticker currently belongs to, this is the tool. However, it does not contrast itself with sibling tools such as list_smart_lists, get_smart_list, or get_list_criteria, nor does it say 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?

The readOnlyHint annotation already communicates safety, and the description adds useful context by specifying that it returns metadata fields and is 'Always free.' No contradictions with annotations exist, but no additional behavioral traits such as rate limits or access conditions are disclosed.

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 that states the resource, the fields returned, and the cost-relevant note. Every part earns its place with no redundant wording.

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 one-parameter read-only metadata operation with a complete input schema and an output schema, the description plus structured data fully equips the caller. The lack of sibling routing is a usage-guideline gap rather than a completeness gap.

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%: list_id is documented with its source ('Screen id from list_smart_lists') and concrete examples. The description adds no extra parameter meaning, so the baseline score 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 names a specific resource ('Metadata for one stock screen') and enumerates the exact fields returned (display name, short description, icon, category ids, parent screen). It is distinguishable from list_smart_lists and get_smart_list_changes, though it does not explicitly name those siblings.

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?

No explicit guidance is given about when to use this tool instead of get_smart_list or list_smart_lists. The only contextual hint is 'Always free,' which addresses cost rather than selection criteria, leaving the agent to infer usage from the name and sibling list.

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 discloses important behavioral details: it is descriptive rather than advisory, and it specifies detailed rate limits and pricing (anonymous 5/day by IP, signed-in 10/day, power users 50/day, then $0.02 via x402 USDC). This gives the agent crucial cost and quota awareness that annotations do not cover.

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 paragraph, moderately long but every sentence carries operational or semantic value. It front-loads the tool's content, then usage guidance, then cost/limit context. It could be broken into bullet points, but it is not padded with fluff.

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 an output schema present, the description need not detail return shapes. It covers the single optional parameter thoroughly, states the tool's nature, provides a complementary sibling use case, and fully documents access quotas and pricing. Nothing an agent needs to invoke it 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 coverage is 100%, so the baseline is 3. The description adds value by explaining why the sections parameter exists ('Pick sections to keep the answer small') and by enumerating the section options in prose, reinforcing the schema's enum and helping the agent choose appropriately.

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 'Today's market conditions' and enumerates exactly what the tool returns: daily overview narrative, fear & greed index, per-sector scores, rotation, cycle phase, and categorized news. This clearly differentiates it from the sibling smart-list and watchlist tools, which are about lists rather than market conditions.

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 'Pick sections to keep the answer small', telling the agent how to control response size. It also names a complementary use case: 'Pairs with get_my_watchlist for "how is my watchlist doing against the market?"' and clarifies the tool is 'Descriptive, not a recommendation', giving a clear when-not-to-use boundary.

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 authentication needs (Bearer token), cost structure ($0.05 via x402), daily allowance tiers, and clarifies the output is descriptive, not a recommendation. These go well beyond the annotation and give the agent critical operational 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 core function is front-loaded in the first sentence, followed by auth and cost details. The description is slightly verbose with the allowance breakdown, but every sentence carries information. It is efficient without being terse.

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, covering return-value details. The description explains the main data categories (analytics and headlines), authentication, and cost. With only 3 optional parameters and no nested objects, nothing essential 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 coverage is 100% with descriptive text for limit, offset, and news_days. The description adds no parameter-specific semantics beyond what the schema already provides, so the baseline 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 names a specific verb+resource: retrieving analytics and headlines for the user's own watchlist. It explicitly differentiates from get_smart_list_metrics by adding 'plus the latest headlines' and 'for your own watchlist', and it cites a user-facing phrase, making the 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 clearly states the context: operates on 'your own watchlist' and requires a session token, implying authenticated user data. It references get_smart_list_metrics for comparison but does not explicitly say when to use one over the other or provide exclusions, so it falls short of a 5.

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 discloses paging behavior (max 200 per call), per-tier rate limits (5/10/50 per day), and overage pricing via x402 USDC — exactly the kind of quota/auth/cost context annotations don't carry. It also adds a 'Descriptive, not a recommendation' disclaimer that matters when an agent relays results to a user. Nothing in the description contradicts 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 single sentence is front-loaded with the core purpose ('Symbols currently in a stock screen') before moving to paging, disclaimer, and quota/pricing details. Each clause carries distinct information — content type, safety framing, cost model — with no filler. Dense but not bloated, meriting a 4.

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 output schema covers return values, all three parameters are fully documented, and the safety profile is annotated. The description fills the remaining operational gaps: paging cap, entitlement tiers, overage cost, and the non-recommendation caveat. No critical information an agent would need to invoke this 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 coverage is 100%, with limit, offset, and list_id each already documented in the schema, so the baseline is 3. The description adds minor reinforcement ('max 200 per call' mirrors the limit maximum) and its screen examples echo the list_id values, but it doesn't introduce new parameter meaning. 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 centers on a specific resource and action — 'Symbols currently in a stock screen' — and grounds it with concrete examples (today's earnings, golden-cross buy signals, AI beneficiaries). The word 'currently' plus the content examples distinguish it from sibling tools like get_smart_list_changes and get_smart_list_metrics, and list_smart_lists is referenced as the source of screen ids. An agent can tell what this returns 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 implies when to call it — to fetch current members of a known screen — and conveys operational constraints (paging, daily allowance), but it never names an alternative or states a when-not-to-use condition. Routing relative to siblings like get_smart_list_changes or get_smart_list_metrics must be inferred from the word 'currently' rather than stated explicitly. Clear context, but no exclusions or alternatives.

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 readOnlyHint=true already covering the read-only safety profile, the description adds genuinely useful behavioral context: the baseline can span multiple rebuildsaine, and there is a daily free allowance with per-call overage pricing via x402 (USDC). 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 core behavior is front-loaded in the first clause, followed by useful examples and pricing details. It is a little dense as one long sentence, but every part earns its place 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?

Given only one well-documented parameter, an output schema, and a readOnly annotation, the description is complete enough for an agent to invoke the tool correctly. It explains what the result represents, mentions the baseline semantics, and covers quota/cost constraints.

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 list_id is already fully described in the schema as 'Screen id from list_smart_lists whose additions and removals you want.' The description adds conceptual framing about stock screens and changes, but it does not materially extend parameter-level semantics beyond the schema, so the baseline 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 opens by stating exactly what the tool reports — symbols that entered or left a stock screen since its last recorded baseline — and illustrates with concrete examples such as new golden crosses and momentum-leader dropouts. This clearly distinguishes it from sibling tools like get_smart_list (current membership), get_smart_list_metrics, 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 examples give a clear sense of when this tool is appropriate: detecting membership changes over a rebuild-spanning baseline rather than viewing the current list. However, it does not explicitly name sibling alternatives or state when not to use it, so it stops short of a 5.

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?

While readOnlyHint=true already indicates a read-only operation, the description adds valuable behavioral context: pagination capped at 200 per call, per-tier daily allowances with overage payment ($0.05 per call via x402 USDC), and the guarantee that it returns no live quotes. These traits are not inferable from annotations alone.

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?

Four sentences, each delivering distinct value: what the tool returns, what it excludes and what to use instead, a disclaimer, and the pricing model. The core capability is front-loaded and no sentence is redundant or 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?

With an output schema present, the description doesn't need to explain return values. It fully covers the data scope, paging behavior, pricing, exclusions, and alternatives, providing all the context an agent needs to decide whether and how to invoke the tool.

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 covers 100% of the parameters with explicit descriptions, so the description carries little additional burden. It reinforces paging semantics by saying 'paged, max 200 per call' and points to list_smart_lists as the source for list_id, but these are largely restatements of the schema rather than new meaning.

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 ('returns') plus a specific resource ('per-symbol analytics for a stock screen') and enumerates the exact data points: earnings reaction, drift, next earnings date, expectations score, options-implied move, and technical signals. It also explicitly excludes live quotes, market cap, and valuation ratios, distinguishing it from quote APIs and 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?

Explicitly states when not to use this tool ('returns no live quotes, market cap or valuation ratios') and directs the agent to 'a quote API' as the alternative. It also adds a usage caveat ('Descriptive, not a recommendation') and clarifies paging limits, giving clear boundaries for invocation.

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 only declare readOnlyHint=true, but the description adds substantial behavioral context: no live quotes, per-section as_of timestamps, free-tier limits and overage pricing, and the non-recommendation stance. This goes well beyond what the annotations 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 long but every sentence carries decision-relevant information: what the tool returns, what it excludes, how to trim output, and cost/access details. It is front-loaded with the core purpose, though the pricing details could arguably be moved to a separate note.

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?

Combined with the output schema and annotations, the description fully covers what the tool does, what it does not do, how to select sections, behavioral caveats, and usage limits. An agent has everything needed to decide when to call it and how 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 coverage is 100% and the sections parameter already documents the default set and explicit opt-in for inside_sentiment. The description reinforces this and adds the useful gloss that inside_sentiment means 'how the business reads from the inside,' providing slight extra meaning 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, memorable framing: everything QuantApe derives about ONE stock that a quote API can't tell you. It enumerates concrete sections and explicitly contrasts itself with quote APIs, making its scope and differentiation clear.

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 to use a quote API for live quotes, market cap, and valuation ratios, and instructs the agent to pick sections to keep the answer small. It also flags inside_sentiment as opt-in and describes the tool as descriptive rather than a recommendation, giving clear decision rules.

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 only supply readOnlyHint, but the description adds substantial context: rate limits and pricing tiers (5/10/50 per day, $0.01 via x402), the share-class normalization rule (GOOG -> GOOGL), the direction convention for lead_lag (from the symbol's point of view), and a descriptive-not-recommendation disclaimer.

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?

Dense but front-loaded: the primary return shape comes first, then the mechanism, then caveats and pricing. Almost every sentence earns its place, though the pricing/rate-limit sentence is somewhat long and could be tightened.

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 an output schema, annotations, and 100% schema coverage already present, the description need not explain return values — and it still covers semantics, edge cases, caveats, and cost. Nothing an agent needs to call it 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 coverage is 100%, so the baseline is 3, but the description adds genuine conceptual meaning beyond the schema — it explains what residual correlation is (co-movement after removing market/sector effects) and what lead_lag represents, enriching the enum values with interpretation rather than just restating them.

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 with scope: the stocks that move most with a given ticker, ranked by strength, each with cluster info. It distinguishes the resid_corr vs lead_lag outputs and clearly sets this apart from siblings like cluster_context and get_stock_insights.

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 guidance on parameter choice: use the default resid_corr for peers/true co-movement, switch to lead_lag for directed lagged relationships — and warns that lead_lag is weak/noise out of sample. However, it never explicitly names sibling tools or states when this tool should be preferred over cluster_context.

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 value by stating 'Always free' and clarifying that the tool returns per-tool pricing/allowance information for metered tools below. This goes beyond the annotation without contradicting it, effectively communicating the non-destructive, no-cost nature of the operation.

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, information-dense sentence that front-loads the primary action and resource ('Browse stock screens by category') before listing the categories and output contents. It is efficient and clearly structured, though the long list of categories makes it slightly dense. No redundant or filler phrases are present.

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 presence of an output schema, the description does not need to detail return values. It adequately explains the tool's purpose, the types of screens included, what each entry contains, and its role as a starting point for obtaining screen ids. It could mention that category_id is optional (though the schema does), but overall it is sufficient for a discovery/list tool.

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 input schema covers the only parameter (category_id) at 100% with a clear description. The tool description mentions the category list in prose but does not add any new semantic detail about the parameter itself (e.g., valid formats or interaction with the category list). Since schema coverage is high, the baseline 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 states a specific verb ('Browse') and resource ('stock screens'), enumerates the categories, and specifies exactly what each entry contains (display names, descriptions, member counts, pricing). It also signals its role as the entry point for finding a screen id, clearly distinguishing it from more specific sibling tools like get_smart_list that retrieve a single screen's details.

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 usage context ('Start here to find a screen id') and notes that the tool is free, implying it is a safe discovery step. However, it does not explicitly name alternative tools or conditions under which one should use a sibling (e.g., use get_smart_list for a known screen). The guidance is implied rather than 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?

With only readOnlyHint=true in annotations, the description adds substantial behavioral context: free quotas by user type, overage pricing, input handling for equal-weight versus weighted holdings, share-class collapsing, unknown-ticker handling, hedge flag behavior, and a clear statement that output is descriptive statistics, not investment advice. It consistently reinforces the read-only, non-recommendation nature of 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 long but front-loads the core purpose and metrics before moving to definitions, caveats, and pricing. It is dense yet mostly earns its length by explaining unusual terms like residual correlation and clarifying that diversifiers are not recommendations, though the single-paragraph structure could be easier to scan with bullets.

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 complex portfolio-analysis tool with an existing output schema and readOnlyHint annotation, the description supplies everything an agent needs: what is computed, how regimes are interpreted, how holdings are accepted, edge-case handling, cost/auth context, and the non-advisory nature of results. No material gap remains for correct invocation or interpretation.

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 schema already documents top, regimes, and holdings. The description adds semantic meaning beyond the schema by clarifying that holdings are equal weight by default, that share classes collapse to one company, that out-of-graph tickers appear as unknown, and that high-vol is treated as the conservative regime because correlations rise with volatility.

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 analytical purpose: a diversification read on a holdings list, then enumerates the exact metrics returned (concentration across clusters, Herfindahl index, residual volatility, correlation leaders/laggards, regime conditioning). This makes it unmistakable that the tool analyzes portfolio diversification rather than managing lists or fetching market data like 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?

The description implies when the tool is useful by describing its diversification output and regime options, and it adds practical usage context via daily allowance and x402 pricing. However, it does not explicitly state when to use this tool versus alternatives or when not to use it; the usage is left to inference from the analysis it provides.

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