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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the bar is lower; the description nonetheless adds real behavior — the ranking order is disclosed, and crucially the data-origin caveat (rolling EDGAR Form 4 scan, coverage starts at deployment, capped at 30 days) tells the agent results are incomplete for older windows. It does not describe the shape of each issuer group, which matters since there is no output schema.

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?

Four sentences, front-loaded with what the tool returns before the definitional aside and the coverage caveat. Every sentence earns its place — the cluster-buy definition and the EDGAR coverage limit are non-obvious and load-bearing.

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 five-parameter read-only screening tool with full schema coverage and no output schema, the description covers scope, ordering, filter intent and data-freshness limits. The remaining gap is that it never sketches the per-issuer result structure, which the agent must guess given the absent output schema.

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%, with defaults, bounds and a helpfully worded enum for role, so the schema already carries the parameter burden. The description mainly restates the filter set ('look-back days, minimum total value, minimum insiders and role') and adds only marginal meaning beyond that, plus the cluster-buy hint that is already in the min_insiders schema description.

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 — recent open-market insider purchases (Form 4 code P) — plus the scope (all U.S. public companies) and ordering logic (grouped by issuer, ranked by insider count then dollar value). The market-wide framing implicitly separates it from the company-scoped sibling get_insider_trades, so an agent can route without opening the 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?

Gives clear operating context: it's a screening tool with look-back window, value, insider-count and role filters, and explicitly defines the 'cluster buy' use case with the min_insiders=2 trigger. It stops short of naming the sibling (get_insider_trades) as the alternative for single-company lookups, so the when-not guidance is left to inference.

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