Skip to main content
Glama

AkkruData

by ai.akkrudata
OverviewDiscussionsAdmin

List initial holdings (Form 3) for a company or insider

list_initial_holdings
Read-onlyIdempotent

Initial beneficial-ownership statements (SEC Form 3) and the holdings they report, nested filing -> holdings. A Form 3 is what an insider files on becoming an insider: positions, not trades — there is no transaction date, code, price or direction. Requires ticker and/or insider_cik; for unanchored screening use search_initial_holdings. Each filing carries no_securities_owned (true means the filer reported holding nothing and the holdings array is empty), issuer_cik, insiders, footnotes and source_url_prefix. Non-derivative rows carry shares_owned; derivative rows carry underlying_security_shares / underlying_security_value instead. A holding carries a split_adjusted block only when its filed amounts are not on the current per-share basis. data_quality_flags appears only on rows that fail a consistency check; such rows are withheld unless include_anomalies=true, and anomalies_excluded_on_page says how many this page withheld. Joint filings name several insiders and are reported in _warnings. Results are limited to your plan's history window, which _warnings reports. A ticker outside your plan's company coverage returns 403 PLAN_TIER_INSUFFICIENT_COVERAGE and is still charged. 30 credits per page. POST /api/v1/ownership/initial-holdings; FINANCIAL_API_DOCUMENTATION.md.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageNo1-based page number (default 1).
tickerNoCompany ticker. Provide this and/or insider_cik.
page_sizeNoFilings per page, 1-100 (default 50).
insider_cikNoInsider SEC CIK, digits only. Provide this and/or ticker.
relationshipNoAny of "is_director", "is_officer", "is_ten_percent_owner", "is_other"; OR semantics, evaluated per filing.
include_anomaliesNoInclude holdings carrying data_quality_flags (excluded by default).
no_securities_ownedNotrue: only filings that report no holdings at all; false: only filings with holdings; omit: both.
exclude_likely_mergedNoDrop filings whose amendment merge is only probable.
include_unresolved_amendmentsNoInclude amendments that could not be matched to an original filing.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already mark readOnlyHint and idempotentHint true, and the description adds substantial behavioral context: nesting shape, no_securities_owned edge semantics, split_adjusted conditional presence, anomaly withholding unless include_anomalies=true, joint-filing warnings, plan history limits, 403 charging behavior, and credits per page. No contradiction with annotations.

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

Conciseness5/5

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

Dense but every sentence earns its place: definition and differentiation come first, followed by response semantics, edge cases, warnings, costs, and endpoint. Although long, there is no filler, and with no output schema the detail is justified.

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?

Despite having no output schema, the description covers the response structure, conditional fields, filtering semantics, error behavior, plan limits, credits, and endpoint. An agent has enough context to call the tool correctly and interpret the result without additional discovery.

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

Parameters4/5

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

The schema covers 100% of parameter descriptions, so the baseline is 3, but the tool description adds meaningful parameter context: ticker can trigger PLAN_TIER_INSUFFICIENT_COVERAGE and still be charged, no_securities_owned=true means the holdings array is empty, and include_anomalies gates data_quality_flags rows. This goes beyond simple schema repetition.

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 opening sentence names the exact deliverable: 'Initial beneficial-ownership statements (SEC Form 3) and the holdings they report, nested filing -> holdings.' It also clarifies the Form 3 context ('positions, not trades') and distinguishes itself from the sibling for unanchored screening, so an agent can tell this tool apart from search_initial_holdings.

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?

The description explicitly states the prerequisite ('Requires ticker and/or insider_cik') and gives a when-not condition: 'for unanchored screening use search_initial_holdings.' It also warns about a plan-coverage failure mode for tickers, which helps an agent decide whether this tool is appropriate before calling.

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

All AkkruData toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources