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

Annotations already indicate read-only and idempotent, so the description does not need to repeat that. The description reveals useful behavioral constraints: non-derivative transactions only, row filtering for price outliers and duplicate filings, and exclusion of issuers without a ticker. It also specifies the output is in USD and limited to 200 rows, which adds transparency beyond annotations.

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 reasonably concise, packing a lot of information into a few sentences. It is front-loaded with the core purpose, then details the lists, and finally the technical constraints. There is some redundancy with the schema (repeating list names), but overall it is efficient.

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?

The description is fairly complete for a read-only tool with a simple output schema. It explains the filtering rules, the meaning of windows, and the row limitaving. The only possible missing context is the exact field list for the returned trades, but it references get_insider_trades for that, so an agent can look it up. This is sufficient.

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 input schema already provides a comprehensive description for each parameter: the 'list' parameter has an enum with all allowed values and a description repeating them, and the 'limit' parameter has range and default. The description adds clarity by explaining what each list returns and the underlying logic, but it doesn't add new semantic meaning to the parameters themselves. Given 100% schema coverage, a baseline of 3 is appropriate.

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 clearly states the tool's purpose: provides ready-made insider trading screens with specific list names and their definitions. It references the livermore.club website and explicitly lists all six screen types, making it evident what each list returns. This goes beyond a generic statement of 'get insider lists'.

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 explains the meaning of each list and the criteria (e.g., cluster-buys, ceo-cfo-buys, top-buys-week etc.), which helps agents select the appropriate list. It also notes that windows count back from now by SEC filing time and provides details on transaction types. However, it does not explicitly mention when to use this tool versus alternatives like get_insider_trades, but the context is clear enough.

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