Skip to main content
Glama
edgar13f-mcp

edgar13f-mcp

by Serios16

diff_holdings

Compare two 13F quarter-end holdings for a manager on a shared as-of date to identify position-level changes, and filter by issuer or CUSIP to narrow large filings.

Instructions

Position-level changes between period_a and period_b, each computed with get_holdings_as_of rules on the same as_of and consolidated by (cusip, put_call, sh_prn). Large managers file tens of thousands of rows: narrow with issuer, cusip or max_positions. as_of means what was publicly filed by that date.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "cik": "<cik>",
      "period_a": "<period_a>",
      "period_b": "<period_b>",
      "as_of": "<as_of>"
    },
    "name": "diff_holdings"
  }
}

Input Schema

NameRequiredDescriptionDefault
cikYesSEC Central Index Key; leading zeros optional. Resolve a manager's name to its CIK with find_manager.
as_ofYesISO-8601 knowledge date: the answer uses only what was publicly filed on EDGAR by this date.
cusipNo
issuerNoKeep only rows whose name_of_issuer contains this text (case-insensitive, whitespace collapsed); combined with cusip as AND. The response lists matched_cusips.
period_aYesForm 13F report period: a calendar quarter-end date.
period_bYesForm 13F report period: a calendar quarter-end date.
max_positionsNoReturn only the largest positions (by value); the response adds total_positions, truncated and order.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.2.2

TDQS

A4/5.0
Behavior4/5

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

No annotations exist, so the description carries the full burden, and it discloses several non-obvious traits: rows are consolidated by (cusip, put_call, sh_prn), as_of is a point-in-time knowledge cutoff ('what was publicly filed by that date'), and result sets can be enormous. It does not mention rate limits, empty-result behavior, or how new versus exited positions are represented.

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?

Three tight sentences, front-loaded with the core definition before the operational caveat and the as_of clarification. Some of the as_of wording duplicates the schema, which is the only real waste.

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

Completeness3/5

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

With no output schema, the description must explain return values, and it only partly does: it names the consolidation key, the max_positions truncation behavior, and the matched_cusips echo via the schema. It never says what a 'change' row actually contains (share delta, value delta, added/closed position markers), which is the central thing an agent needs from a diff tool.

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 86%, so the schema already explains cik, as_of, issuer, period_a/b and max_positions in detail. The description largely restates the as_of semantics already in the schema, and its consolidation tuple describes output grouping rather than parameter meaning. Baseline 3 applies when the schema does the heavy lifting.

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?

States a specific verb and resource: position-level changes between period_a and period_b, and immediately distinguishes itself from the sibling get_holdings_as_of by saying each row is computed with that tool's rules on the same as_of. An agent can tell what this computes without opening the schema.

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

Usage Guidelines4/5

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

Gives actionable operating guidance: 'Large managers file tens of thousands of rows: narrow with issuer, cusip or max_positions.' That tells the agent how to cope with the result size, and the reference to get_holdings_as_of implies the relationship between the two tools. It stops short of an explicit 'use this instead of get_holdings_as_of when you need period-over-period deltas' rule.

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