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

Annotations already declare a safe, idempotent, closed-world read, so the extra context is genuine value: the description discloses the exact computation methodology (YTD quarters de-cumulated, cover-page shares, ADR caps via the ADS ratio) shared with capital_structure, and the specific null conditions (non-USD reporters, no tagged debt, SIC 6000-6499 getting P/B instead of EV multiples). It also explains that as_of rebuilds the table on a past date, which the annotations cannot convey.

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-loaded with the core purpose, then organized into a metrics block and a peer block, so an agent can scan for what it needs. It is dense and long, and the metric enumeration is a comma list, but essentially every clause carries information an agent would otherwise have to guess.

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 compensates by cataloguing the returned fields (market cap through 1-year total return, plus the quarter and accession), the peer-selection provenance fields, and the null/edge-case behavior. For a complex six-parameter analytical tool this covers everything needed to call it correctly and interpret the result.

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 baseline is 3; the description beats that by explaining the default peer-selection cascade and how peer_source, peers and n_peers interact, plus the meaning of peer_selection and named_as_peer_by in the result. It does not restate parameter formats (max 15, YYYY-MM-DD), but it adds real semantics about what the defaults produce rather than just repeating field labels.

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?

Names a specific analysis (comparable-company analysis) and enumerates the resource precisely: trailing valuation and operating metrics for a company and its peers with peer medians, subject excluded. It explicitly scopes itself as trailing-only with no estimates, and the closing pointer to capital_structure for full capital structure plus history cleanly separates it from the nearest 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?

States when peers must be supplied versus defaulted (board's proxy peer group first, then TSR/performance-graph set, falling back to 4-digit SIC widened to 3 then 2 digits by revenue proximity). It closes with an explicit routing rule: use capital_structure for one company's full capital structure and 8-quarter history.

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