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

Goes well beyond readOnlyHint=true: discloses the row granularity (one row per sector+industry pair requiring aggregation), that totalMarketCap is always NULL and therefore cannot answer market-share questions, that blank-sector rows are dropped, that an {error} dict is returned when Postgres is unavailable, and the underlying source and scale.

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?

Front-loads the scope and the portfolio exclusion, and nearly every sentence carries operational information. The all-caps emphasis and the 'how much of the market is tech' aside add length but do convey a real capability limit.

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 no output schema, the description fully compensates by specifying the exact return shape, the aggregation requirement, the always-NULL field, and the error case — everything an agent needs to interpret the response 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?

Zero-parameter tool, so the baseline is 4; the schema is empty and the description correctly confirms 'No arguments.' There is nothing further to document.

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?

States a specific verb and resource ('how the covered universe splits across sectors and industries') and immediately scopes it as 'the whole catalog, NOT a portfolio,' which separates it from get_portfolio_positions without opening either schema.

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?

Explicitly names the alternative ('For a named portfolio use get_portfolio_positions') and the condition that selects it, plus states 'No arguments' so the agent knows no filter setup is needed.

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