Skip to main content
Glama

AkkruData

by ai.akkrudata
OverviewDiscussionsAdmin

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

get_initial_holding_stats
Read-onlyIdempotent

Aggregates over Form 3 filings in a filing-date window: filing_count, no_securities_filing_count, distinct_insiders, filings_with_multiple_filers, holdings_count (with non-derivative / derivative split), shares_owned_total (non-derivative rows, current adjusted basis) and underlying_shares_total (derivative rows, current adjusted basis) — two different units, not to be added together — plus earliest/latest_filing_date and corporate_action_crossing. Filing counts include filings that report no holdings. Read _warnings before using any total. holding_ids (paged) lists the rows the holding totals were built from; fetch them with get_initial_holdings_by_id. A ticker outside your plan's company coverage returns 403 PLAN_TIER_INSUFFICIENT_COVERAGE and is still charged. 40 credits + 5 per 1000 participating holdings. POST /api/v1/ownership/initial-holdings/stats; FINANCIAL_API_DOCUMENTATION.md.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cikNoCompany SEC CIK, 1–10 digits as a string; leading zeros are optional; any CIK the company has filed under. Provide cik or ticker, not both.
tickerNoCompany ticker; any symbol the company has traded under. Provide this and/or insider_cik.
ids_pageNoProvenance page (default 1).
as_of_dateNoYYYY-MM-DD window end (filing date), must not be in the future.
start_dateNoYYYY-MM-DD window start (filing date).
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.
ids_page_sizeNoProvenance ids per page, 1-1000 (default 200).
is_derivativeNoRestrict holding totals to non-derivative (false) or derivative (true) rows; omit for both.
include_anomaliesNoInclude holdings carrying data_quality_flags (excluded by default).
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. Changed2 schema fields changed
    • addedInput schema / properties / cik
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Company SEC CIK, 1–10 digits as a string; leading zeros are optional; any CIK the company has filed under. Provide cik or ticker, not both.",
+  "title": "Cik"
+}
    • changedInput schema / properties / ticker / description
      Previous value: -"Company ticker. Provide this and/or insider_cik."New value: +"Company ticker; any symbol the company has traded under. Provide this and/or insider_cik."
  2. First observed

TDQS

A3.9/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavioral context: 403 PLAN_TIER_INSUFFICIENT_COVERAGE with charges still applied, the credits formula (40 + 5 per 1000 holdings), the _warnings field requirement, the unit mismatch between shares_owned_total and underlying_shares_total, and the note that filing counts include no-holding filings. This is far beyond what the structured fields convey.

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?

A single dense paragraph, but it is front-loaded with the aggregation scope and output fields and every clause carries information (units, warnings, cost, endpoint). It reads as a run-on wall of text rather than cleanly separated concerns, which costs it the top mark.

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

Completeness4/5

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

With no output schema and 12 parameters, the description carries the burden of describing returns and mostly delivers, naming the key output fields, the provenance list, the warnings field, cost, and the coverage error. It names fields like corporate_action_crossing and earliest/latest_filing_date without fully defining them, leaving minor gaps.

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 schema already documents each parameter, and the baseline is 3. The prose largely restates output semantics rather than adding parameter-level meaning; it does reinforce the filing-date window framing but contributes little the schema does not already carry.

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

Purpose4/5

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

The description opens with a specific verb and resource ('Aggregates over Form 3 filings in a filing-date window') and enumerates the exact metrics produced, so an agent knows precisely what comes back. It differentiates itself from the row-level counterpart by pointing to get_initial_holdings_by_id for the underlying rows. It stops short of distinguishing itself from neighbors like list_initial_holdings or search_initial_holdings, so it is clear but not fully sibling-aware.

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

Usage Guidelines3/5

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

It gives operational caveats ('Read _warnings before using any total', 'two different units, not to be added together') and routes to get_initial_holdings_by_id for provenance rows. However it never states when to choose this aggregation over the sibling list/search/insider-stats tools, leaving the core when-to-use decision implied.

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