market_analyst_ratingsReturn the analyst rating consensus and recent rating changes for one ticker. The results are third-party opinions.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | The maximum number of results to return. | |
| symbol | Yes | The ticker symbol. Example: AAPL. |
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | ||
| meta | Yes | ||
| billing | Yes | ||
| warnings | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, which already cover the safety profile. The description adds the 'third-party opinions' framing, which is useful context indicating the data's provenance. No contradictions with annotations. However, it doesn't detail limit behavior or pagination beyond schema defaults, so it adds modest but not rich 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?
Two sentences with zero waste - states what it returns and the data provenance. Front-loaded with the key purpose. Slightly terse but appropriately minimal for a read-only lookup tool.
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, and the 2-parameter schema is fully documented. The description covers the purpose and data provenance adequately. However, given the large sibling set and the open-world annotation, brief guidance on use cases or what 'rating changes' entails would improve completeness, though 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 description coverage is 100%, with both parameters (symbol, limit) having descriptive text including an example. The description adds nothing parameter-specific beyond what the schema already covers. Baseline 3 applies since the schema fully documents both 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 clearly states it returns 'analyst rating consensus and recent rating changes for one ticker' - a specific verb+resource+scope. It distinguishes from siblings by specifying 'one ticker' (vs market_quote or news_* which serve different purposes). Could be slightly sharper on what distinguishes it, but it's clear enough about purpose.
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 notes results are 'third-party opinions' but provides no guidance on when to use this tool vs alternatives like market_quote, market_fundamentals, or market_earnings. With 27 sibling tools in the market/news space, an agent gets no direction on which to pick for analyst-specific data versus fundamental or price data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool targets a distinct resource-action combination (catalog items, datasets, macro data, market data, news, politics, account). Even within the market_ prefix, tools are clearly separated by resource type (quote, fundamentals, earnings, ratings, profile). No two tools appear to perform the same operation.
The naming follows a consistent noun_verb pattern with domain prefixes: catalog_, datasets_, macro_, market_, news_, politics_. The verb style is consistent (describe, list, search, request, submit, return-type verbs like indicator and quote). Slight deviation with account_request_upgrade vs account_upgrade_status, and some verbs double as noun forms (quote, indicator, preview), but overall the convention is predictable.
At 28 tools, the count is on the high side, but it serves a broad data platform spanning seven distinct domains (catalog, datasets, macro, market, news, politics, account). Each domain earns multiple tools to cover its surface, and the domains are broad enough to justify the volume. Slightly heavy, but reasonable given the scope.
The surface covers the full discovery-to-delivery workflow for data: list, describe, preview, request (catalog), plus direct dataset access. Market data has symbols search, quotes, price history, fundamentals, earnings, ratings, ETFs, and profile. Minor gaps include no bulk quote or multi-ticker endpoints, and there's no tool for reading an existing catalog request's status, but core workflows are well-covered.