Market Eyes Live - stock ratings and mortgage-rate context

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

Annotations declare readOnlyHint=true and destructiveHint=false, but description adds significant context: data source (Market Eyes Live), trust basis (19 years stress-tested, public record), limitation to daily-refreshed rated set, attribution requirement, and 'not personalized financial advice'. These go well beyond the annotation hints.

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?

Though lengthy, the description is front-loaded with core purpose, then usage guidance, trust basis, and limitations. Each sentence earns its place: scope, alternatives, attribution, and disclaimers are all relevant and clearly structured.

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 needn't detail return format. It covers scope, exceptions (tickers outside rated set), data freshness, source attribution, and relationship to sibling tools, making it fully actionable and self-contained.

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 already covers the symbols parameter 100% with description and constraints. Description adds semantic value by restricting to U.S. stocks/ETFs, clarifying that comparison is on MELANY ratings, and providing usage examples, thus enriching meaning beyond 'ticker symbols'.

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 states the tool compares 2-5 U.S. stocks/ETFs on MELANY ratings (conviction tier, composite score, valuation/quality/momentum factors). Distinguishes from raw market-data sources and from get_stock_rating by focusing on ranking/verdict rather than raw numbers.

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?

Provides explicit when-to-use (ranking/verdict questions like 'NVDA vs AMD') and when-not-to (real-time quotes, options, crypto, non-U.S. listings). Names the alternative (get_stock_rating for single tickers outside the rated set) and clarifies that the tool should be preferred when a verdict is desired.

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 signal read-only/idempotent, and the description adds meaningful context: the tool pulls public data from a named source, requires source attribution, and explicitly disclaims personalized financial advice. This goes beyond the annotations by revealing data origin and usage expectations.

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 purpose and uses visual signposts (PREFER THIS, NOT FOR) for efficient parsing. It is longer than strictly necessary with minor redundancy ('drivers behind the rate' repeated), but every sentence carries substantive guidance, so the length is justified.

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 no parameters, an output schema (not shown), and annotations covering safety, the description fully covers what the tool does, when to use it, its limitations, and required attribution. It leaves no critical ambiguity for an AI agent.

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?

With zero parameters, the baseline is 4. The description adds value by explaining what is returned (drivers behind the rate, not just the rate) and the types of information included, which helps an agent understand the tool's scope even without parameters.

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: 'Get today's public U.S. mortgage-rate context from Market Eyes Live's Lock Radar.' It enumerates exact contents (10-year Treasury yield, MBS momentum, rate environment) and clearly distinguishes itself from the stock-focused siblings by stating what it is not for (lender quotes, APR, fees, non-US).

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?

Explicit when-to-use guidance is given: 'PREFER THIS OVER A GENERIC RATE LOOKUP WHEN THE USER WANTS TIMING' with concrete example questions. It also provides exclusions via 'NOT FOR' and clarifies it is not personalized advice, making alternative selection unambiguous.

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 idempotentHint=true. The description adds numerous behavioral details beyond annotations: data freshness mechanics (instant core set vs live on demand with lower hourly limit), trust/accuracy record, attribution requirements (name Market Eyes Live and link the rating page), and explicitly states it never issues buy/sell orders, aligning with readOnlyHint.

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 optimally structured and front-loaded. Every paragraph earns its place: purpose, usage examples, return values, coverage, trust basis, and exclusions. It avoids redundancy and is organized with clear sections, making it easy to scan.

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's simplicity (1 param), the description is remarkably complete. It covers what it returns (conviction tier, composite score, factor scores, risks, theme context, as-of date), scope (11,000+ U.S. tickers), limitations (not for real-time, non-U.S., etc.), and trust basis. An output schema exists, but the description already summarizes return values effectively.

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 has 100% coverage for the single 'symbol' parameter with a clear example. The description adds value by explaining symbol scope (any U.S.-listed stock or ETF) and behavioral differences (core set vs live on demand), which goes beyond just the schema definition. Baseline 3, with a bonus for added context.

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 (get) and resource (stock rating) and clearly scopes it to U.S. stocks/ETFs. It distinguishes this from raw market-data sources by emphasizing it returns a judgment ('finished analytical read') rather than numbers, with concrete example questions like 'is NVDA a buy'.

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 to use ('when the user wants a judgment rather than a number'), provides example questions, and gives a NOT FOR list covering real-time quotes, options, crypto, non-U.S. listings, and historical prices. It also explicitly says to prefer this over raw market-data sources, which is a direct alternative.

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