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

Annotations already declare readOnly/openWorld=false, and the description adds real behavioral context beyond them: newest-first ordering, numeric values returned as strings exactly as filed, every object carrying accession and filed_date, and the {data, total, limit, offset} paging envelope. The notable coverage limitation (Forms 3/5 only live-forward since 2026-09-23) is disclosed twice, which prevents silent data gaps. Not a 5 only because auth/quota/error behavior is untouched.

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 what the tool returns, then scope, then filters, then the paging envelope — a sensible order with no filler sentences. Some parenthetical stacking (the 3/5 live-forward note appears in both the opening and the filter sentence) makes it denser than necessary.

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?

No output schema exists, and the description compensates by describing the return envelope, guaranteed fields (accession, filed_date), and a key data-format quirk (numbers as strings). Combined with sibling context (get_insider_filing, get_schema) and annotations, an agent has enough to call it correctly; only authentication and pagination limits beyond the schema's max 25 are unstated.

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 description coverage is 100%, so the schema already explains cik, owner_cik, ticker, form_type, limit, offset, since and until in detail. The description restates much of that (form_type meanings, owner_cik = one insider across every issuer) rather than adding new semantics; the useful addition is framing cik as issuer CIK vs. owner_cik as insider CIK, which the schema leaves slightly implicit.

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?

Opens with a specific verb+resource ('List normalized SEC insider ownership filings') and enumerates the form types covered plus the fields returned, so the agent knows exactly what comes back. It does not name the sibling get_insider_filing as the single-filing alternative, so the plural list vs. single-fetch distinction is only implied by 'List' and the paging envelope.

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 clear usage context: filter by ticker/CIK/owner_cik/form_type/since, and 'hosted and already normalized — no EDGAR crawling... needed', which tells the agent why this beats raw EDGAR. No explicit when-not or named alternative inside the corpus of sibling tools (e.g., use get_insider_filing for a single accession) is given.

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