get_watchlist

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context beyond that: it enumerates the analytical fields returned, notes plan-dependent fields (Plus/Pro and Pro-only), warns that the response grows large on many assets, and clarifies that an empty watchlist is not a failure. This fully discloses the tool's behavior.

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 front-loaded with the core purpose, follows with a detailed field enumeration, and ends with usage guidance. Every sentence adds value, though the 'supports requests about...' sentence is somewhat redundant with the first sentence. It is dense but efficient for such a rich output.

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 focuses on high-level semantics and usage decisions. It fully explains the tool's scope, the meaning of an empty watchlist, plan-dependent field availability, and alternatives for narrower queries. This is complete for an analyst agent to select and invoke 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?

The tool has zero parameters and the input schema is empty, so there are no parameter semantics to elaborate. The description fully covers the invocation context by describing what the tool operates on (the user's saved watchlist) and what it returns. Baseline for 0 params is 4, and the description exceeds any need by clarifying plan-dependent outputs.

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+resource: 'Get analytical summaries for every ticker on the user's saved watchlist.' It clearly differentiates from siblings by naming get_summary for single tickers and get_watchlist_changes for change-only queries, making the purpose distinct and unambiguous.

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 states when to use this tool ('only for questions that span the whole tracked set') and when not to ('for a question about one specific ticker use get_summary instead', 'prefer get_watchlist_changes' for change detection). It also advises using add_to_watchlist first and clarifies that an empty watchlist is a valid state, not an error.

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