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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description is free to add operational detail and does: up to 25 results, newest-first ordering, percentile statistics computed over ALL matches (not just returned rows), USD millions, and the definition of deal size as value of 100% of the target. It also discloses plan gating and per-day search limits, which are not in any structured field.

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?

Three tight sentences: what it does, what it returns, and the commercial/unit caveats. Result shape and limits are front-loaded before the plan note, and nothing repeats the annotations or schema.

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 10-parameter, zero-required tool with no output schema, the description does the important work: return composition, percentile semantics, units, and result cap are all spelled out. What is missing is filter-combination behavior and the fact that there is no pagination beyond the 25-row cap, which matters for an agent that may want more results.

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 80%, so the schema handles most parameter meanings; the description still adds value by fixing units (USD millions) and clarifying that deal-size filters refer to 100% of the target, which prevents a common misinterpretation. It says nothing about require_multiple, gics vs naics precedence, or how multiple filters combine, leaving some gaps.

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: searching Equitest's curated M&A transaction database, and the second sentence clarifies exactly what comes back (deals plus p25/median/p75 multiples). The purpose is unambiguous. It never names a sibling to contrast with, though the siblings (company financials, valuation, industry benchmarks, list_companies) are far enough apart that confusion is unlikely.

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?

Usage is only implied: an agent infers this is the tool for comparable-transaction analysis, but the description never says when to use it versus get_company_valuation or get_industry_benchmarks, nor when to skip it. Plan availability and daily search limits are stated, which is a useful gating hint but not usage guidance.

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