gold-silver-analytics

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

Annotations already declare readOnlyHint and openWorldHint. Description adds 'Analytical, not a recommendation' and lists output components (9-factor score, DQS, stage, etc.), providing useful behavioral context beyond 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?

Single sentence of 30 words, front-loaded with key information, no filler or redundancy. Every word 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?

Given the simplicity (1 param, no output schema, annotations present), the description adequately covers what the tool does and outputs. No missing information.

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 the single parameter 'ticker' fully (100% coverage). The description does not add extra semantic meaning beyond what the schema provides, so 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 clearly states 'Re-Rate (RR) Score projection for one junior precious-metals miner' with specific verb 'get' and resource 'RR score'. It distinguishes from siblings which are for screening, listing, or searching tickers.

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 specifies use for 'one junior precious-metals miner', implying it's for a single company's detailed score. Context signals and sibling tools indicate alternatives but no explicit exclusions. Clear context for when to use.

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 (safe) and openWorldHint=true (data may change). The description adds behavioral context: it operates on a 'free-subset' (not the full universe) and warns against interpreting results as a 'best stock' list. 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?

Two well-structured sentences. The first concisely lists optional functionality; the second provides a cautionary note. No redundant or extraneous information.

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, the description could briefly note what fields are returned (e.g., ticker, score). However, the tool is simple (filtered list) and the name implies typical fields. The input parameters are well-explained, and the readOnly/openWorld hints cover safety. Minor gap in output description.

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 covers all 5 parameters with descriptions. The description adds significant meaning: clarifies metal values (Au/Ag), jurisdiction as substring, stage with exact codes, sort direction and year (2028 RR Score descending), and limit as capping. This goes beyond the schema alone.

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 uses specific verb 'screen' and defines resource as 'free-subset feed'. It clearly lists filterable attributes (metal, jurisdiction, stage) and optional sorting/capping. The sibling tools (get_rr_score, list_tickers, search_tickers) serve different purposes, so this tool is well-distinguished.

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 'structured screen over the free-subset feed' and warns it is 'never a best stock list', implying it is for analytical filtering rather than ranking recommendations. However, it does not explicitly contrast with siblings or provide exclusion criteria (e.g., when to use list_tickers instead).

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 openWorldHint=true. The description adds value by specifying that only symbols and a count are returned (no scores), and it discloses the universe size and free-subset scope, which are beyond annotation capabilities.

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 efficiently conveys the tool's purpose and output without extraneous 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?

The description explains the return value (list of symbols plus count) and the universe. No output schema exists, but for a simple list tool, this is nearly complete. It could mention the output format (e.g., array of strings), but not essential.

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 are zero parameters, so the baseline score is 4. The description correctly implies that no inputs are needed, which is consistent with the empty input 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 the tool lists ticker symbols and a count, specifying it covers the Gold Silver Analytics free-subset universe (~279). It distinguishes from siblings like search_tickers (which implies searching) and get_rr_score (which implies scoring).

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 usage for obtaining a list of all covered tickers without scores. It does not explicitly state when not to use it or mention alternatives, but the context of sibling tools provides some guidance.

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 it as read-only and open-world. The description adds behavioral details: fuzzy matching, case-insensitivity, returning free-subset rows, and matching fields. No contradictions.

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 core purpose and behavior. Every word adds value, no 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 the simple tool (1 param, no output schema), the description covers purpose, behavior, and alternative usage. It is complete enough for an agent to select and invoke 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% with a single parameter 'query' described as substring matching. The description adds 'fuzzy' and 'case-insensitive' context, but the schema already conveys the substring nature. Baseline 3 with minor addition.

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 it's a fuzzy lookup for ticker symbols or company names with case-insensitive substring matching. It distinguishes itself from the sibling tool get_screen_data, which is for structured filter/rank.

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 advises to use get_screen_data for structured filter/rank instead, providing clear guidance on when not to use this tool. The implied usage is for fuzzy substring searches.

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