gold-silver-analytics

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety profile is covered. The description adds meaningful behavioral context: it is a projection (not historical fact), for a 'free-subset' (suggesting limited or ungated data), includes specific score factors, and explicitly disclaims being a recommendation. It does not contradict annotations and provides value beyond them.

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 two sentences, with the first front-loading the full output list and the second adding a concise disclaimer. Every word earns its place — no fluff, no repetition of schema details, and the structure is easily scannable.

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-ticker read-only analytics tool with no output schema, the description fully enumerates what the response will contain (overall and factor scores, DQS, stage, jurisdiction, and 2028/2029 projections), plus a disclaimer. Given the low complexity (1 param, no pagination, no nesting), this is complete and sets accurate expectations.

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 for the only parameter (ticker) is 100%, with a clear description of the ticker symbol format. The tool description does not add additional parameter guidance, but it doesn't need to since the schema is self-sufficient. This meets the baseline for full 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?

The description states a specific verb ('get') and resource ('Re-Rate (RR) Score projection for one junior precious-metals miner') and enumerates the exact output contents (overall 9-factor score, nine factor scores, DQS, stage, jurisdiction, 2028/2029 projections). This clearly distinguishes it from sibling tools like list_tickers or search_tickers, which are about ticking finding/listing rather than detailed single-ticker analytics.

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 makes clear this is for a single ticker's analytical projection, implying use when you need that specific data for a known ticker. It does not explicitly mention alternatives or when-not-to-use, but the scope ('one junior precious-metals miner') provides clear context relative to the siblings. A caveat 'Analytical, not a recommendation' also helps set user expectations.

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 and openWorldHint annotations are complemented by the description's disclosure that this operates on a 'free-subset feed' (a limitation) and that output is an 'analytical ranked classification' not a recommendation. This adds behavioral context beyond the annotations, though it doesn't detail rate limits or pagination. No contradiction with annotations.

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

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

The description is highly concise: two sentences, front-loaded with the core functionality and ending with a caveat. Every phrase adds value, from the free-subset scope to the filter/sort options. There is no redundant wording 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?

Despite no output schema, the description covers the tool's purpose, filters, sorting, limit, and a key caveat. It doesn't describe the exact output fields, but given the interactive nature and sibling context, this is reasonably complete. The free-subset limitation and analytical classification add important context. A fully complete description might mention whether results include score values or just tickers, but it's not a critical omission.

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 parameters are fully documented in the schema. The description restates a few parameter values (e.g., Au/Ag, country, stage values) but doesn't add meaning beyond the schema except clarifying that jurisdiction means a country (though the schema already states that). It adds no syntax or format details, so a 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 performs a structured screen over the free-subset feed, with specific filters (metal, jurisdiction, stage) and optional sorting and limit. This distinguishes it from siblings like get_rr_score (single score) and search_tickers (search) by emphasizing a ranked analytical classification. The verb 'screen' plus resource 'coverage universe' is specific and 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 provides clear context: it's for filtered/ranked screening over a limited feed, and explicitly notes 'never a best stock list' to exclude financial advice usage. It doesn't name alternatives explicitly, but the context of filters and the analytical caveat gives a good sense of when to use it. A minor gap is not mentioning when to prefer search_tickers or list_tickers.

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 and openWorldHint annotations already establish safety and world-dependence, but the description adds useful behavioral details: it returns every symbol in a specifically bounded universe, includes a count, and excludes scores. This goes beyond the annotations by clarifying the exact output content and scope.

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 two short sentences, with no wasted words. It front-loads the core action ('Every ticker symbol...') and packs in scope, count, and exclusion of scores efficiently.

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 no-parameter, no-output-schema list tool, the description conveys the key output aspects: the full set of covered tickers, the approximate count, and that scores are not included. It is complete enough for an agent to know what to expect, though it does not specify the exact return structure (e.g., separate count field vs. count in the list).

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

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

The tool has zero parameters, so the baseline for this dimension is 4 per the rubric. The description appropriately focuses on the output semantics rather than parameters, and no additional parameter information is needed.

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 lists every ticker symbol in the Gold Silver Analytics free-subset coverage universe (~279), plus a count, and explicitly notes it returns symbols only, not scores. This distinguishes it from siblings like get_rr_score and search_tickers by specifying the resource (all covered tickers) and scope (free subset).

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 the full list of covered tickers) but does not explicitly name alternatives or state when not to use it. The phrase 'Symbols only — no scores' hints that other tools handle scores, but this guidance is not 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?

Annotations already declare readOnlyHint and openWorldHint, and the description adds behavioral details beyond those: case-insensitive substring matching and returning rows that contain the query. The phrase 'free-subset rows' is somewhat vague but does not contradict 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?

Two concise sentences, front-loaded with the primary action and followed by a useful alternative reference. No wasted words.

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 search tool with read-only annotations and no output schema, the description covers the core behavior and provides an alternative. The 'free-subset' phrase introduces minor ambiguity but does not undermine overall completeness.

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 only parameter 'query' is fully described in the schema. The description does not add meaning 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 uses a specific verb ('lookup') and resource ('tickers'), clearly stating it matches by symbol or company name via fuzzy substring. It also explicitly distinguishes itself from get_screen_data, making its purpose 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 clearly indicates a use case (fuzzy lookup) and explicitly recommends an alternative (get_screen_data) for structured filter/rank. However, it does not contrast with list_tickers, leaving a slight ambiguity for when to use each sibling.

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