form4api-mcp

get_insider_directory

Read-only

Browse insiders alphabetically by surname. Returns the A-Z rail with a count per letter, plus one page of insiders under the requested letter. Omit letter to get the rail and totals with no rows.

Instructions

Browse insiders alphabetically by surname. Returns the A-Z rail with a count per letter, plus one page of insiders under the requested letter. Omit letter to get the rail and totals with no rows.

Names come from EDGAR surname-first ("HENNEMAN JOHN B III"), so alphabetical order is order by surname. Casing in the source is inconsistent and is not normalised here.

This lists only insiders with at least 3 non-superseded transactions, capped at the 5,000 most active — the same set as the insiders sitemap shard, so the two cannot drift. To find someone outside that set, use GET /v1/insiders?name= which searches every filer. Rebuilt daily; refreshedAt reports when. limit is accepted as an alias for per_page. Not plan-gated.

One row per FILER GROUP. A fund group files a single Form 4 listing several reporting owners — the fund, its GP, its management company — and each is a real EDGAR filer with its own CIK. Listing all of them spent about 11% of this capped surface describing the same actors more than once, so browse shows one per group and filerGroupSize says how many others share those exact transactions. The others are not hidden: each keeps its own profile and is still returned by GET /v1/insiders?name=.

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	1-based page number within the letter. Defaults to 1.
`limit`	No	Alias for per_page.
`letter`	No	Single letter A-Z to list, or "#" for names that do not begin with a letter. Omit to get the A-Z rail and totals without any rows.
`per_page`	No	Rows per page. Defaults to 200, maximum 500. `limit` is accepted as an alias; if both are given, per_page wins.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.9.7Oct 14, 2026

addedInput schema / properties / limit

Added value: +{
+  "description": "Alias for per_page.",
+  "type": "integer"
+}

changedInput schema / properties / per_page / description

Previous value: -"Rows per page. Defaults to 200, maximum 500."New value: +"Rows per page. Defaults to 200, maximum 500. `limit` is accepted as an alias; if both are given, per_page wins."

Addedv1.9.6Aug 25, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries the real behavioral burden and does so richly: the 5,000-insider cap, the 3-transaction threshold, daily rebuild with `refreshedAt`, the shared sitemap shard guaranteeing no drift, absence of plan gating, and the filer-group dedup rule with `filerGroupSize` explaining omitted actors. This is well beyond what the annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and return shape are front-loaded in the first two sentences, and each paragraph covers a distinct concern (ordering, dataset membership, filer-group dedup). The closing paragraph on filer groups is somewhat long and includes a supporting statistic, but it earns its place by explaining why rows are deduplicated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and four parameters, the description fills the gap by describing the rail/counts payload, `refreshedAt`, and `filerGroupSize`, plus how the returned names are ordered and where the data comes from. An agent can call and interpret this tool correctly from the definition alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description restates the `letter` omission behavior and the `limit`/`per_page` alias rather than adding new parameter-level meaning (e.g., no guidance on page bounds interaction beyond what the schema already states). The extra 'casing is not normalised' note describes the returned data, not the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource (browse insiders alphabetically by surname) and immediately describes the return shape (A-Z rail with per-letter counts plus one page). It also names the alternative surface (GET /v1/insiders?name=), so the agent can distinguish this from the other insider-listing siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit routing conditions: omit `letter` for the rail and totals with no rows, and use GET /v1/insiders?name= to find someone outside the capped 5,000-insider set. It also states eligibility (3+ non-superseded transactions) and that the tool is not plan-gated, which is exactly the when/when-not information an agent needs.

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

get_insider_directory

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools