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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that data comes from Yahoo Finance and no API key is required, plus the return includes ratings and price targets. However, it doesn't describe pagination or limits on the history length or clarify if the tool filters by wholesaler by default, though the schema covers wholesaler_ids. Given the annotations, a 3 is appropriate.

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 well-structured with a clear summary followed by bulletized use cases and a source note. It is concise and front-loads the core output. The only minor inefficiency is the trailing 'Source: Yahoo Finance' line which, while useful, could be integrated. Still, it earns its place by explaining data provenance.

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 tool has a complex schema with many parameters, but many are optional and have defaults. The description focuses on the primary use case of fetching ratings/price targets. However, it doesn't mention the wholesaler_ids filtering or source_resource_id caching, which are advanced but present in the schema. Given the existence of a rich schema and output schema, the description is adequate for most agents to call the tool correctly. Could add a note on typical output format, but not critical.

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 has extensive descriptions for parameters like symbol and wholesaler_ids, covering a high degree of detail. However, the schema coverage is reported as 0%, meaning the schema's descriptions are not counted? Actually the context says coverage 0%, but the schema text clearly describes each parameter. The description itself only mentions the core symbol and the upgrades/downgrades flag, but it does not add much beyond what the schema already provides. Since the schema descriptions are detailed, the description adds little, but with 0% coverage baseline would be 3. The description does mention the return of fromGrade/toGrade which param 'include_upgrades_downgrades' controls, providing slight enhancement.

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 fetches analyst ratings, price targets, and upgrade/downgrade history. It distinguishes itself from siblings by its focus on analyst consensus (buy/sell/hold) and price targets, which none of the sibling tools (e.g., GetPriceHistory, GetTickerInfo) cover.

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 lists three 'Use this tool when' scenarios, such as checking Wall Street consensus or needing price target range. It also notes the data source (Yahoo Finance) and that no API key is required, setting clear expectations. However, it does not explicitly state when not to use it or name an alternative tool, but given the clear use cases, this is sufficient.

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