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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: tier-dependent default sector resolution and the fact that every tracked holding sector is returned with its own quadrant. It does not discuss rate limits, auth requirements, or what happens when a stock is held by no tracked sector.

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 the payload contents front-loaded and the fallback behavior placed where it matters. The first sentence is a long multi-clause enumeration but every item listed is a distinct returned field that the agent otherwise could not know (no output schema exists), so little is wasted.

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 only two parameters, full schema coverage, and no output schema, the description correctly takes on the job of enumerating return contents and explaining tier-dependent defaults. The main remaining gap is edge-case behavior, such as what is returned if the stock is not held by any tracked sector ETF.

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%, so the schema already documents both `symbol` and `sector` with examples, and the baseline is 3. The description does add real meaning for `sector` by explaining it as the comparison 'lens' and describing the default resolution when it is omitted, but the `symbol` parameter gets no additional treatment beyond the schema.

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 the specific resource (one stock's performance measured against a sector ETF that holds it, called its 'lens') and enumerates exactly what is returned: 1w–1y returns, gap to sector, relative-strength trend, valuation, next earnings date, and per-sector quadrants. This is clearly distinguishable from the sibling zensei_sector_detail, which operates at the sector level rather than the stock-vs-sector level.

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 final sentence gives explicit, actionable context about the `sector` parameter: omit it and the free tier falls back to a broad S&P 500 sector holding the stock, while Premium uses the largest-weight sector. That is clear conditional behavior, but the description does not name alternatives (e.g., when to reach for zensei_sector_detail or zensei_view_indicators instead).

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