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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context beyond those: weekly close frequency, once-per-trading-day refresh, no intraday data, coverage limits, holdings-overlap warnings, and error behavior for unknown tickers. It does not contradict the 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 dense but every clause carries information: scope, outputs, alternatives, exclusions, data cadence, limitations, and error handling. The key purpose is front-loaded, and the alternative routing appears mid-description in a natural place. No filler or repetition of schema details is present.

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 complex analysis tool with an output schema and safety annotations, the description covers everything needed to invoke it correctly: input constraints, supported asset types, data freshness, excluded instruments, error behavior, and sibling routing. It is complete enough that an agent can select and call this tool without further inference.

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 already has 100% description coverage for positions and detail, so the baseline is 3. The description adds context beyond the schema by clarifying the asset universe, position count range, and ticker-resolution requirement, which helps the agent choose valid parameter values. It does not need to repeat schema-level normalization rules, so a 4 is warranted.

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 names a specific verb and resource: whole-portfolio risk and diversification analysis for 2 to 30 US stocks or ETFs. It enumerates concrete outputs (Euler risk contributions, diversification ratio, effective number of bets, correlation blocks) and immediately distinguishes itself from the compare_pair sibling.

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 says 'Use compare_pair for just two assets,' which is a direct alternative-routing instruction. It also gives exclusions (no crypto, no foreign listings, no inverse/leveraged funds) and tells the agent to resolve unknown tickers with resolve_symbol first, making when-to-use and when-not-to-use clear.

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?

Beyond the readOnlyHint/idempotentHint/destructiveHint annotations, the description reveals important behaviors: popular pairs are served from a precomputed matrix, any other pair is computed on demand from weekly returns, data refreshes once per trading day, and unknown tickers produce an error. These are precisely the behavioral traits an agent needs to set 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 dense but every sentence earns its place: output list, coverage universe, computation mode, example, commutativity, limitations, refresh cadence, and error handling. The most important purpose is front-loaded, and details are logically organized rather than padded.

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 pairwise comparison tool with an output schema and safety annotations, this description is complete: it defines the symbol universe, data frequency, computation path, return value caveats, and failure mode. An agent can determine correct usage and expected behavior without needing supplemental 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 already documents both parameters at 100% coverage, so the baseline is 3. The description adds material value by explicitly stating 'Symbol order does not matter' and providing a concrete example (a=QQQ, b=VOO), which removes a likely ambiguity about whether parameter order is significant.

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 specifies the verb 'Compare' with a resource ('a pair of US stocks or ETFs') and enumerates the exact outputs computed, from correlation and beta to holdings overlap. This clearly differentiates it from siblings like symbol_profile and analyze_portfolio, which are single-asset or multi-asset portfolio tools.

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 gives strong usage context: it covers US-listed equities/ETFs only, excludes crypto, foreign listings, inverse/leveraged funds, and intraday data, and explicitly instructs agents to call resolve_symbol first for unknown tickers. It stops short of naming sibling alternatives such as find_diversifiers or analyze_portfolio for when a single comparison is not the right fit.

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?

Although annotations already mark this as read-only and idempotent, the description adds substantial behavioral context: the raw list may contain leveraged/inverse ETNs, volatility products, and illiquid micro-caps, so name and kind must be checked before presenting results. It also discloses weekly-close data, once-per-day refresh, and error behavior for unknown tickers. This goes well beyond the 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 dense but every clause earns its place: purpose, output elements, caveats, coverage scope, data frequency, and error handling. The key purpose is front-loaded, and the warnings are packed into a compact but readable warning block. Nothing is redundant with the schema or annotations.

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 one-parameter read-only tool with an output schema, the description covers all essential operational knowledge: coverage universe, refresh cadence, error behavior, and important content warnings. An agent has enough information to invoke it correctly and to interpret results safely.

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% and the single parameter has a clear description ('Ticker to diversify away from, e.g. QQQ'). The tool description adds extra meaning by specifying that the ticker must be a US stock or ETF and that unknown tickers error out. This is valuable enrichment beyond the schema field.

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: it finds assets with the lowest or most negative 3-year correlation to a given US stock or ETF. It also mentions the output includes name and kind, making the tool's function and scope clear. This distinguishes it from siblings like symbol_profile or compare_pair.

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 gives clear context for when the tool is appropriate: US-listed stocks and ETFs only, no crypto, no foreign listings, no intraday data. It also tells the agent to resolve unknown tickers via resolve_symbol first, which is direct cross-tool guidance. It does not explicitly name alternative siblings for related tasks, but the conditions are strong enough for an agent to select it correctly.

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, idempotentHint, and destructiveHint, so the safety profile is fully covered. The description adds useful context about the coverage universe (~4,700 US stocks/ETFs) and that it can match company names or partial tickers, but it does not substantially expand on behavioral details beyond what annotations and schema already indicate.

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 only two sentences, with the core purpose and an example stated first, followed by the usage directive. Every sentence earns its place, and there is no redundant or filler content.

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 is simple with only two parameters, rich annotations, and an output schema. The description covers the purpose, usage timing, and scope, so an agent has everything needed to select and invoke it 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 description coverage is 100%, so the parameter semantics are already fully documented in the schema. The description adds a helpful example for 'query' but no additional meaning for 'limit' or deeper formatting details, so the baseline 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 a specific action ('Find the ticker'), the target resource (PairBook's ~4,700 covered US stocks and ETFs), and gives a concrete example ('nvidia' -> NVDA). It is clearly distinguished from siblings like compare_pair or weekly_returns because it is specifically a name-to-ticker resolver.

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 tells the agent when to use this tool: 'Call this before other tools whenever the exact ticker is uncertain or a lookup returned not-found.' This provides clear procedural guidance relative to all siblings, making the intended invocation order 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?

Beyond the annotations, the description adds meaningful behavioral context: data uses weekly closes, refreshes once per trading day, excludes intraday data, covers only US-listed stocks/ETFs, and returns an error for unknown tickers. These details clarify what the agent can expect and pre-empt common failure modes.

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 dense but efficient: it front-loads the returned profile fields, then provides routing guidance, coverage constraints, refresh cadence, and error handling. Every sentence contributes necessary information without 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 single required parameter, the presence of an output schema, and the annotations, the description is complete. It covers intended use, sibling alternatives, universe restrictions, data frequency, and error behavior, leaving no practical gap for an agent deciding whether and how to call this tool.

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 already documents the single symbol parameter with an example, so schema coverage is 100%. The description adds extra semantic context by clarifying that the symbol must be a US stock or ETF, describing coverage limits, and noting that unknown tickers produce an error resolvable with resolve_symbol.

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 identifies the resource (a single US stock or ETF) and enumerates the metrics returned, including beta, volatility, returns, drawdown, and correlated assets. It also distinguishes itself from find_diversifiers, though it lacks an explicit action verb and does not differentiate against all siblings like compare_pair or analyze_portfolio.

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 gives explicit routing guidance: 'For diversification candidates use find_diversifiers.' It also states when the tool should be used versus alternatives by defining the universe and exclusions, and directs users to resolve_symbol for unknown tickers before calling this tool.

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 readOnly, idempotent, and non-destructive, so the description adds substantial behavioral context: W-FRI weekly closes, most recent last, aligned end Fridays, ~4,700 US-listed symbols only, exclusions, once-per-trading-day refresh, and error behavior for unknown tickers. 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?

One dense paragraph with useful details front-loaded: series format and target use come first, coverage and refresh constraints follow. Slightly long but every clause conveys a distinct operational fact.

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 two-parameter tool with rich annotations and an output schema, the description covers the essential usage context: data scope, exclusions, refresh cadence, calendar alignment, and error handling. An agent has enough information to select and call the tool 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?

Input schema covers both parameters at 100%, and the description adds extra meaning beyond the schema: symbol domain restrictions (US-listed stocks/ETFs, no crypto/foreign/inverse funds), unknown-ticker error behavior, and the weekly cadence. This meaningfully supplements the schema's basic type descriptions.

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 returns a weekly return series for one US stock or ETF, with an explicit purpose ('for custom correlation or risk math'). The single-symbol scope and series alignment details distinguish it from sibling tools like compare_pair, analyze_portfolio, and find_diversifiers.

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?

Names the intended use case ('custom correlation or risk math') and explicitly instructs users to resolve unknown tickers with resolve_symbol first. It does not enumerate when to choose this tool over every sibling, but the constraints and workflow guidance are clear.

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