Skip to main content
Glama
theodor90

form4api-mcp

by theodor90
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

get_insider_scorecard

Read-only

Assess an insider's buy track record using historical hit rates and average/median returns from discretionary open-market purchases. Includes a sample-sufficiency guard to prevent misleading statistics.

Instructions

Get insider buy track-record scorecard (Pro plan+). Returns the historical hit rate and average/median return of an insider's discretionary open-market buys (TransactionCode=P, excluding 10b5-1 plans and derivatives), plus their best and worst scored buy. Scores use absolute return (NOT market-adjusted) anchored at the filing-date close. A 'hit' is a scored buy whose 3m (or 6m) return is positive. Use this over GET /v1/insiders/{cik}/summary when you specifically want a scored track record (with a sample-sufficiency guard) rather than raw totals; use GET /v1/insiders/leaderboard (Business+) to rank many insiders by this same methodology. Score fields (hitRate3m, avgReturn3m, etc.) are null when the insider has fewer than 5 matured scored buys (sampleSufficient=false), preventing misleading statistics from small samples. Requires Pro plan or higher (402 PLAN_REQUIRED on Free/Starter). Returns 404 NOT_FOUND if the CIK isn't tracked. Computed live — no caching. Note: all return fields (HitRate3m, AvgReturn3m, MedianReturn3m, etc.) are stored as FRACTIONS — 0.05 means +5%, -0.10 means -10%.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cikYesInsider's SEC CIK, exact match.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / cik / description
      Added value: +"Insider's SEC CIK, exact match."
  2. First observedv1.0.0

TDQS

A4.9/5.0
Behavior5/5

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

Beyond annotations (readOnlyHint, openWorldHint), description details scoring methodology (absolute return, anchored at filing close), hit definition, handling of small samples, no caching, and specific return value formats (fractions). 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?

Description is comprehensive but efficiently structured: opens with purpose, then methodology, usage guidance, edge cases, and format notes. Every sentence adds value without unnecessary repetition.

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?

Covers all essential aspects: required parameter, output fields (with fraction notation), sample sufficiency guard, error scenarios, plan restrictions, and computational behavior. Suitable for correct invocation despite lack of output schema.

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?

Input schema fully describes the single parameter (cik) with 'exact match'. Description adds contextual value by mentioning plan requirement and 404 error for missing CIK, which aids agent understanding of parameter validation and error handling.

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?

Description clearly states it returns a scored track record of insider buys, differentiates from sibling tools like get_insider_summary (raw totals) and get_insider_leaderboard (ranking many insiders), and specifies the methodology and output fields.

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?

Explicitly describes when to use this tool (for scored track record) versus alternatives, notes plan requirement (Pro+), mentions error conditions (402, 404), and explains when fields are null due to sample insufficiency.

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

Deploy Server

Other Tools