Skip to main content
Glama

Get institutional holdings

get_institutional_holdings

Retrieves reported institutional holdings for one ticker across supported retained 13F history. Filter by manager name or CIK, report period, filing dates, amendments, share class and shares versus PUT/CALL positions. Returns typed quantities, native reported values, manager identities and source support. Identifier and filing-join checks hold ambiguous records; report dates differ from filing dates, and native value scales remain explicit. Current requests recheck stale mirror metadata; historical/pinned reads never switch snapshots. Continue with the returned snapshot ID/hash, as_of, filters and cursor or next_offset. Uses account allowance or prepaid credit.

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": {
      "ticker": "<ticker>",
      "context": "<context>",
      "llm_model": "<llm_model>"
    },
    "name": "get_institutional_holdings"
  }
}

Input Schema

NameRequiredDescriptionDefault
as_ofNoAvailability cutoff, separate from event/period filters. Historical reads never refresh.
limitNoMatching typed observations per page; default32.
cursorNoArchive continuation token; reuse with snapshot ID/hash, as_of and unchanged filters.
offsetNo
tickerYes
contextYesUser's research goal in one short sentence (max 300 characters); include relevant ticker and topic. Exclude names, contact/account/portfolio details, credentials and source text.
date_toNoInclusive native date upper bound, selected by date_field.
put_callNoReported 13F position category; SHARES excludes PUT/CALL reports.
date_fromNoInclusive native date lower bound, selected by date_field.
llm_modelYesYour model identifier, if known (e.g. gpt-6); otherwise leave unknown. Exclude credentials and private deployment names.
date_fieldNoDate meaning; defaults to period for facts/macro/holdings/returns, event for insider trades, observation for options/short volume, scheduled for calendar.
manager_cikNo
share_classNo
snapshot_idNoPin continuation to the returned snapshot ID; reuse with snapshot_hash and as_of.
manager_nameNo
report_periodNo
snapshot_hashNo
filters_sha256NoReuse the returned filter hash unchanged with continuation pages.
conversation_idNoPass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
include_amendmentsNo
max_snapshot_age_hoursNoRequested verification-age tolerance: default1hour for retained archives,24hours for closing-price references. Record dates and publication cadence are separate.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "as_of": {
      -        "$ref": "#a1"
      -      },
      -      "billing_notice": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "add_credits_url": {
      -            "$ref": "#a5"
      -          },
      -          "code": {
      -            "const": "signup_credit_exhausted"
      -          },
      -          "message": {
      -            "$ref": "#a4"
      -          },
      -          "plans_url": {
      -            "$ref": "#a5"
      -          },
      -          "remaining_requests": {
      -            "const": 0
      -          }
      -        },
      -        "required": [
      -          "code",
      -          "message",
      -          "remaining_requests",
      -          "add_credits_url",
      -          "plans_url"
      -        ],
      -        "type": "object"
      -      },
      -      "context": {
      -        "anyOf": [
      -          {
      -            "additionalProperties": false,
      -            "properties": {
      -              "artifact_id": {
      -                "$ref": "#a6"
      -              },
      -              "available_at": {
      -                "$ref": "#a1"
      -              },
      -              "content_hash": {
      -                "type": "string"
      -              },
      -              "observed_through": {
      -                "$ref": "#a1"
      -              }
      -            },
      -            "required": [
      -              "artifact_id",
      -              "content_hash",
      -              "observed_through",
      -              "available_at"
      -            ],
      -            "type": "object"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "data": {
      -        "items": {
      -          "additionalProperties": false,
      -          "properties": {
      -            "available_issuer_selectors": {
      -              "additionalProperties": false,
      -              "properties": {
      -                "dimensions": {
      -                  "$ref": "#/$defs/d"
      -                },
      -                "fiscal_years": {
      -                  "items": {
      -                    "maximum": 9007199254740991,
      -                    "minimum": -9007199254740991,
      -                    "type": "integer"
      -                  },
      -                  "maxItems": 100,
      -                  "type": "array"
      -                },
      -                "metrics": {
      -                  "$ref": "#/$defs/d"
      -                },
      -                "scope": {
      -                  "const": "retained_issuer_observations"
      -                },
      -                "truncated": {
      -                  "type": "boolean"
      -                }
      -              },
      -              "required": [
      -                "metrics",
      -                "dimensions",
      -                "fiscal_years",
      -                "scope",
      -                "truncated"
      -              ],
      -              "type": "object"
      -            },
      -            "coverage": {
      -              "enum": [
      -                "complete_for_retained_scope",
      -                "partial_archive_scan",
      -                "bounded_snapshot",
      -                "unavailable"
      -              ]
      -            },
      -            "family": {
      -              "const": "institutional_holdings"
      -            },
      -            "freshness": {
      -              "additionalProperties": false,
      -              "properties": {
      -                "age_seconds": {
      -                  "$ref": "#aa"
      -                },
      -                "capture_age_seconds": {
      -                  "$ref": "#aa"
      -                },
      -                "evaluated_at": {
      -                  "$ref": "#a1"
      -                },
      -                "latest_record_at": {
      -                  "$ref": "#a2"
      -                },
      -                "max_snapshot_age_seconds": {
      -                  "exclusiveMinimum": 0,
      -                  "type": "number"
      -                },
      -                "publication_cadence_verified": {
      -                  "const": false
      -                },
      -                "refresh_status": {
      -                  "enum": [
      -                    "not_required",
      -                    "historical_no_refresh",
      -                    "newer_admission_unverified",
      -                    "source_clock_unknown"
      -                  ]
      -                },
      -                "source_captured_at": {
      -                  "$ref": "#a7"
      -                },
      -                "source_verified_at": {
      -                  "$ref": "#a7"
      -                },
      -                "status": {
      -                  "enum": [
      -                    "fresh",
      -                    "stale",
      -                    "unknown",
      -                    "historical"
      -                  ]
      -                },
      -                "verification_age_seconds": {
      -                  "$ref": "#aa"
      -                },
      -                "verification_scope": {
      -                  "const": "filing_inventory"
      -                }
      -              },
      -              "required": [
      -                "status",
      -                "evaluated_at",
      -                "source_captured_at",
      -                "age_seconds",
      -                "max_snapshot_age_seconds",
      -                "latest_record_at",
      -                "publication_cadence_verified",
      -                "refresh_status"
      -              ],
      -              "type": "object"
      -            },
      -            "held_records": {
      -              "$ref": "#a9"
      -            },
      -            "limitations": {
      -              "$ref": "#ab"
      -            },
      -            "matched_records": {
      -              "$ref": "#a9"
      -            },
      -            "omitted_records": {
      -              "$ref": "#a9"
      -            },
      -            "records": {
      -              "items": {
      -                "additionalProperties": false,
      -                "properties": {
      -                  "accession": {
      -                    "$ref": "#a2"
      -                  },
      -                  "amendment_type": {
      -                    "$ref": "#a2"
      -                  },
      -                  "cusip": {
      -                    "$ref": "#a2"
      -                  },
      -                  "figi": {
      -                    "$ref": "#a2"
      -                  },
      -                  "filing_date": {
      -                    "$ref": "#a2"
      -                  },
      -                  "is_amendment": {
      -                    "$ref": "#a2"
      -                  },
      -                  "manager_cik": {
      -                    "$ref": "#a2"
      -                  },
      -                  "manager_name": {
      -                    "$ref": "#a2"
      -                  },
      -                  "native_details": {
      -                    "anyOf": [
      -                      {
      -                        "additionalProperties": false,
      -                        "properties": {
      -                          "attributes": {
      -                            "additionalProperties": {
      -                              "$ref": "#a2"
      -                            },
      -                            "type": "object"
      -                          },
      -                          "clocks": {
      -                            "items": {
      -                              "additionalProperties": false,
      -                              "properties": {
      -                                "name": {
      -                                  "$ref": "#a4"
      -                                },
      -                                "precision": {
      -                                  "enum": [
      -                                    "instant",
      -                                    "date",
      -                                    "period",
      -                                    "unknown"
      -                                  ]
      -                                },
      -                                "role": {
      -                                  "enum": [
      -                                    "period",
      -                                    "event",
      -                                    "report",
      -                                    "expiration",
      -                                    "scheduled",
      -                                    "observation"
      -                                  ]
      -                                },
      -                                "value": {
      -                                  "$ref": "#a2"
      -                                }
      -                              },
      -                              "required": [
      -                                "name",
      -                                "role",
      -                                "value",
      -                                "precision"
      -                              ],
      -                              "type": "object"
      -                            },
      -                            "maxItems": 8,
      -                            "type": "array"
      -                          },
      -                          "measurements": {
      -                            "items": {
      -                              "additionalProperties": false,
      -                              "properties": {
      -                                "name": {
      -                                  "$ref": "#a4"
      -                                },
      -                                "unit": {
      -                                  "$ref": "#a2"
      -                                },
      -                                "value": {
      -                                  "type": [
      -                                    "string",
      -                                    "number",
      -                                    "null"
      -                                  ]
      -                                }
      -                              },
      -                              "required": [
      -                                "name",
      -                                "value",
      -                                "unit"
      -                              ],
      -                              "type": "object"
      -                            },
      -                            "maxItems": 128,
      -                            "type": "array"
      -                          }
      -                        },
      -                        "required": [
      -                          "attributes",
      -                          "measurements",
      -                          "clocks"
      -                        ],
      -                        "type": "object"
      -                      },
      -                      {
      -                        "type": "null"
      -                      }
      -                    ]
      -                  },
      -                  "observed_at": {
      -                    "$ref": "#a2"
      -                  },
      -                  "period_end": {
      -                    "$ref": "#a2"
      -                  },
      -                  "position": {
      -                    "$ref": "#/$defs/c"
      -                  },
      -                  "put_call": {
      -                    "$ref": "#a2"
      -                  },
      -                  "record_id": {
      -                    "type": "string"
      -                  },
      -                  "report_period": {
      -                    "$ref": "#a2"
      -                  },
      -                  "reported_at": {
      -                    "$ref": "#a2"
      -                  },
      -                  "reported_value": {
      -                    "$ref": "#/$defs/c"
      -                  },
      -                  "share_class": {
      -                    "$ref": "#a2"
      -                  },
      -                  "source_kind": {
      -                    "type": "string"
      -                  },
      -                  "support": {
      -                    "additionalProperties": false,
      -                    "properties": {
      -                      "content_hash": {
      -                        "$ref": "#a3"
      -                      },
      -                      "document_id": {
      -                        "type": "string"
      -                      },
      -                      "json_pointer": {
      -                        "$ref": "#a2"
      -                      },
      -                      "text_span": {
      -                        "additionalProperties": false,
      -                        "properties": {
      -                          "end": {
      -                            "exclusiveMinimum": 0,
      -                            "maximum": 9007199254740991,
      -                            "type": "integer"
      -                          },
      -                          "start": {
      -                            "$ref": "#a0"
      -                          }
      -                        },
      -                        "required": [
      -                          "start",
      -                          "end"
      -                        ],
      -                        "type": "object"
      -                      }
      -                    },
      -                    "required": [
      -                      "document_id",
      -                      "content_hash",
      -                      "json_pointer"
      -                    ],
      -                    "type": "object"
      -                  },
      -                  "type": {
      -                    "const": "institutional_holding"
      -                  },
      -                  "value_scale": {
      -                    "$ref": "#a2"
      -                  }
      -                },
      -                "required": [
      -                  "record_id",
      -                  "source_kind",
      -                  "support",
      -                  "observed_at",
      -                  "period_end",
      -                  "reported_at",
      -                  "native_details",
      -                  "type",
      -                  "manager_cik",
      -                  "manager_name",
      -                  "accession",
      -                  "report_period",
      -                  "filing_date",
      -                  "cusip",
      -                  "figi",
      -                  "share_class",
      -                  "put_call",
      -                  "position",
      -                  "reported_value",
      -                  "value_scale",
      -                  "is_amendment",
      -                  "amendment_type"
      -                ],
      -                "type": "object"
      -              },
      -              "maxItems": 100,
      -              "type": "array"
      -            },
      -            "retained_records": {
      -              "$ref": "#a9"
      -            },
      -            "status": {
      -              "type": "string"
      -            }
      -          },
      -          "required": [
      -            "family",
      -            "status",
      -            "records",
      -            "retained_records",
      -            "matched_records",
      -            "omitted_records",
      -            "held_records",
      -            "freshness",
      -            "coverage",
      -            "limitations"
      -          ],
      -          "type": "object"
      -        },
      -        "maxItems": 1,
      -        "type": "array"
      -      },
      -      "generated_at": {
      -        "$ref": "#a1"
      -      },
      -      "historical_issuer_ownership_verified": {
      -        "anyOf": [
      -          {
      -            "const": false
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ]
      -      },
      -      "issuer_refresh": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "backfill_from": {
      -            "$ref": "#a8"
      -          },
      -          "backfill_through": {
      -            "$ref": "#a8"
      -          },
      -          "filing_inventory_verified_at": {
      -            "$ref": "#a7"
      -          },
      -          "held_documents": {
      -            "$ref": "#a0"
      -          },
      -          "history_complete": {
      -            "type": "boolean"
      -          },
      -          "status": {
      -            "enum": [
      -              "not_required",
      -              "queued",
      -              "unavailable",
      -              "saved_only"
      -            ]
      -          }
      -        },
      -        "required": [
      -          "status",
      -          "filing_inventory_verified_at",
      -          "backfill_from",
      -          "backfill_through",
      -          "history_complete",
      -          "held_documents"
      -        ],
      -        "type": "object"
      -      },
      -      "limitations": {
      -        "$ref": "#ab"
      -      },
      -      "operation": {
      -        "const": "get_institutional_holdings"
      -      },
      -      "pagination": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "filters_sha256": {
      -            "type": "string"
      -          },
      -          "next_cursor": {
      -            "$ref": "#a2"
      -          },
      -          "next_offset": {
      -            "$ref": "#a9"
      -          },
      -          "offset": {
      -            "$ref": "#a0"
      -          },
      -          "returned": {
      -            "$ref": "#a0"
      -          },
      -          "scan_complete": {
      -            "type": "boolean"
      -          },
      -          "scanned_rows": {
      -            "$ref": "#a0"
      -          },
      -          "snapshot_hash": {
      -            "$ref": "#a2"
      -          },
      -          "snapshot_id": {
      -            "anyOf": [
      -              {
      -                "$ref": "#a6"
      -              },
      -              {
      -                "type": "null"
      -              }
      -            ]
      -          },
      -          "total_matching_records": {
      -            "$ref": "#a9"
      -          },
      -          "total_retained_records": {
      -            "$ref": "#a9"
      -          }
      -        },
      -        "required": [
      -          "offset",
      -          "returned",
      -          "total_retained_records",
      -          "total_matching_records",
      -          "next_offset",
      -          "snapshot_id",
      -          "snapshot_hash",
      -          "filters_sha256"
      -        ],
      -        "type": "object"
      -      },
      -      "query_binding": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "artifactId": {
      -            "$ref": "#a6"
      -          },
      -          "contentHash": {
      -            "$ref": "#a3"
      -          }
      -        },
      -        "required": [
      -          "artifactId",
      -          "contentHash"
      -        ],
      -        "type": "object"
      -      },
      -      "resource": {
      -        "const": "company_dataset"
      -      },
      -      "schema_version": {
      -        "const": "2"
      -      },
      -      "snapshot_captured_at": {
      -        "$ref": "#a7"
      -      },
      -      "sources": {
      -        "items": {
      -          "anyOf": [
      -            {
      -              "additionalProperties": false,
      -              "properties": {
      -                "capture_basis": {
      -                  "enum": [
      -                    "http_response_bytes",
      -                    "retained_export",
      -                    "retained_case"
      -                  ]
      -                },
      -                "content_hash": {
      -                  "$ref": "#a3"
      -                },
      -                "id": {
      -                  "$ref": "#a4"
      -                },
      -                "kind": {
      -                  "enum": [
      -                    "sec_disclosure",
      -                    "government_award",
      -                    "issuer_disclosure",
      -                    "research_input"
      -                  ]
      -                },
      -                "observed_at": {
      -                  "$ref": "#a1"
      -                },
      -                "publication_date": {
      -                  "$ref": "#a8"
      -                },
      -                "publication_precision": {
      -                  "enum": [
      -                    "instant",
      -                    "date",
      -                    "unknown"
      -                  ]
      -                },
      -                "published_at": {
      -                  "$ref": "#a7"
      -                },
      -                "raw_capture_hash": {
      -                  "$ref": "#/$defs/e"
      -                },
      -                "representation": {
      -                  "enum": [
      -                    "provider_json",
      -                    "sec_xbrl",
      -                    "visible_text",
      -                    "retained_research_case"
      -                  ]
      -                },
      -                "retained_record_hash": {
      -                  "$ref": "#/$defs/e"
      -                },
      -                "source_id": {
      -                  "$ref": "#a6"
      -                },
      -                "title": {
      -                  "type": "string"
      -                },
      -                "url": {
      -                  "$ref": "#a5"
      -                }
      -              },
      -              "required": [
      -                "id",
      -                "source_id",
      -                "kind",
      -                "title",
      -                "url",
      -                "published_at",
      -                "publication_date",
      -                "publication_precision",
      -                "observed_at",
      -                "content_hash",
      -                "raw_capture_hash",
      -                "retained_record_hash",
      -                "capture_basis",
      -                "representation"
      -              ]
      -            },
      -            {
      -              "additionalProperties": false,
      -              "properties": {
      -                "calendar_artifact_id": {
      -                  "$ref": "#a6"
      -                },
      -                "calendar_content_hash": {
      -                  "$ref": "#a3"
      -                },
      -                "content_hash": {
      -                  "$ref": "#a3"
      -                },
      -                "id": {
      -                  "type": "string"
      -                },
      -                "kind": {
      -                  "const": "stored_market_data"
      -                },
      -                "observation_count": {
      -                  "$ref": "#a0"
      -                },
      -                "observation_hashes_sha256": {
      -                  "$ref": "#a3"
      -                },
      -                "observed_at": {
      -                  "$ref": "#a1"
      -                },
      -                "providers": {
      -                  "$ref": "#ab"
      -                },
      -                "representation": {
      -                  "const": "reconciled_daily_bars"
      -                },
      -                "title": {
      -                  "type": "string"
      -                },
      -                "url": {
      -                  "$ref": "#a5"
      -                }
      -              },
      -              "required": [
      -                "id",
      -                "kind",
      -                "title",
      -                "url",
      -                "observed_at",
      -                "content_hash",
      -                "providers",
      -                "observation_hashes_sha256",
      -                "observation_count",
      -                "calendar_artifact_id",
      -                "calendar_content_hash",
      -                "representation"
      -              ]
      -            }
      -          ],
      -          "type": "object"
      -        },
      -        "type": "array"
      -      },
      -      "status": {
      -        "enum": [
      -          "available",
      -          "partial",
      -          "unavailable"
      -        ]
      -      },
      -      "ticker": {
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "schema_version",
      -      "resource",
      -      "operation",
      -      "ticker",
      -      "as_of",
      -      "generated_at",
      -      "status",
      -      "context",
      -      "snapshot_captured_at",
      -      "historical_issuer_ownership_verified",
      -      "data",
      -      "sources",
      -      "pagination",
      -      "limitations"
      -    ]
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "error": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "code": {
      -            "enum": [
      -              "unauthorized",
      -              "invalid_input",
      -              "entity_not_found",
      -              "entity_ambiguous",
      -              "outside_entitlement",
      -              "rate_limited",
      -              "data_unavailable",
      -              "insufficient_sample",
      -              "unsupported_security",
      -              "duplicate_request"
      -            ]
      -          },
      -          "message": {
      -            "$ref": "#a4"
      -          },
      -          "recovery": {
      -            "anyOf": [
      -              {
      -                "$ref": "#a4"
      -              },
      -              {
      -                "type": "null"
      -              }
      -            ]
      -          },
      -          "retryable": {
      -            "type": "boolean"
      -          }
      -        },
      -        "required": [
      -          "code",
      -          "message",
      -          "recovery",
      -          "retryable"
      -        ],
      -        "type": "object"
      -      }
      -    },
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "as_of": {
      +        "$ref": "#a1"
      +      },
      +      "billing_notice": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "add_credits_url": {
      +            "$ref": "#a5"
      +          },
      +          "code": {
      +            "const": "signup_credit_exhausted"
      +          },
      +          "message": {
      +            "$ref": "#a4"
      +          },
      +          "plans_url": {
      +            "$ref": "#a5"
      +          },
      +          "remaining_requests": {
      +            "const": 0
      +          }
      +        },
      +        "required": [
      +          "code",
      +          "message",
      +          "remaining_requests",
      +          "add_credits_url",
      +          "plans_url"
      +        ],
      +        "type": "object"
      +      },
      +      "context": {
      +        "anyOf": [
      +          {
      +            "additionalProperties": false,
      +            "properties": {
      +              "artifact_id": {
      +                "$ref": "#a6"
      +              },
      +              "available_at": {
      +                "$ref": "#a1"
      +              },
      +              "content_hash": {
      +                "type": "string"
      +              },
      +              "observed_through": {
      +                "$ref": "#a1"
      +              }
      +            },
      +            "required": [
      +              "artifact_id",
      +              "content_hash",
      +              "observed_through",
      +              "available_at"
      +            ],
      +            "type": "object"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "data": {
      +        "items": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "available_issuer_selectors": {
      +              "additionalProperties": false,
      +              "properties": {
      +                "dimensions": {
      +                  "$ref": "#/$defs/d"
      +                },
      +                "fiscal_years": {
      +                  "items": {
      +                    "maximum": 9007199254740991,
      +                    "minimum": -9007199254740991,
      +                    "type": "integer"
      +                  },
      +                  "maxItems": 100,
      +                  "type": "array"
      +                },
      +                "metrics": {
      +                  "$ref": "#/$defs/d"
      +                },
      +                "scope": {
      +                  "const": "retained_issuer_observations"
      +                },
      +                "truncated": {
      +                  "type": "boolean"
      +                }
      +              },
      +              "required": [
      +                "metrics",
      +                "dimensions",
      +                "fiscal_years",
      +                "scope",
      +                "truncated"
      +              ],
      +              "type": "object"
      +            },
      +            "coverage": {
      +              "enum": [
      +                "complete_for_retained_scope",
      +                "partial_archive_scan",
      +                "bounded_snapshot",
      +                "unavailable"
      +              ]
      +            },
      +            "family": {
      +              "const": "institutional_holdings"
      +            },
      +            "freshness": {
      +              "additionalProperties": false,
      +              "properties": {
      +                "age_seconds": {
      +                  "$ref": "#aa"
      +                },
      +                "capture_age_seconds": {
      +                  "$ref": "#aa"
      +                },
      +                "evaluated_at": {
      +                  "$ref": "#a1"
      +                },
      +                "latest_record_at": {
      +                  "$ref": "#a2"
      +                },
      +                "max_snapshot_age_seconds": {
      +                  "exclusiveMinimum": 0,
      +                  "type": "number"
      +                },
      +                "publication_cadence_verified": {
      +                  "const": false
      +                },
      +                "refresh_status": {
      +                  "enum": [
      +                    "not_required",
      +                    "historical_no_refresh",
      +                    "newer_admission_unverified",
      +                    "source_clock_unknown"
      +                  ]
      +                },
      +                "source_captured_at": {
      +                  "$ref": "#a7"
      +                },
      +                "source_verified_at": {
      +                  "$ref": "#a7"
      +                },
      +                "status": {
      +                  "enum": [
      +                    "fresh",
      +                    "stale",
      +                    "unknown",
      +                    "historical"
      +                  ]
      +                },
      +                "verification_age_seconds": {
      +                  "$ref": "#aa"
      +                },
      +                "verification_scope": {
      +                  "const": "filing_inventory"
      +                }
      +              },
      +              "required": [
      +                "status",
      +                "evaluated_at",
      +                "source_captured_at",
      +                "age_seconds",
      +                "max_snapshot_age_seconds",
      +                "latest_record_at",
      +                "publication_cadence_verified",
      +                "refresh_status"
      +              ],
      +              "type": "object"
      +            },
      +            "held_records": {
      +              "$ref": "#a9"
      +            },
      +            "limitations": {
      +              "$ref": "#ab"
      +            },
      +            "matched_records": {
      +              "$ref": "#a9"
      +            },
      +            "omitted_records": {
      +              "$ref": "#a9"
      +            },
      +            "records": {
      +              "items": {
      +                "additionalProperties": false,
      +                "properties": {
      +                  "accession": {
      +                    "$ref": "#a2"
      +                  },
      +                  "amendment_type": {
      +                    "$ref": "#a2"
      +                  },
      +                  "cusip": {
      +                    "$ref": "#a2"
      +                  },
      +                  "figi": {
      +                    "$ref": "#a2"
      +                  },
      +                  "filing_date": {
      +                    "$ref": "#a2"
      +                  },
      +                  "is_amendment": {
      +                    "$ref": "#a2"
      +                  },
      +                  "manager_cik": {
      +                    "$ref": "#a2"
      +                  },
      +                  "manager_name": {
      +                    "$ref": "#a2"
      +                  },
      +                  "native_details": {
      +                    "anyOf": [
      +                      {
      +                        "additionalProperties": false,
      +                        "properties": {
      +                          "attributes": {
      +                            "additionalProperties": {
      +                              "$ref": "#a2"
      +                            },
      +                            "type": "object"
      +                          },
      +                          "clocks": {
      +                            "items": {
      +                              "additionalProperties": false,
      +                              "properties": {
      +                                "name": {
      +                                  "$ref": "#a4"
      +                                },
      +                                "precision": {
      +                                  "enum": [
      +                                    "instant",
      +                                    "date",
      +                                    "period",
      +                                    "unknown"
      +                                  ]
      +                                },
      +                                "role": {
      +                                  "enum": [
      +                                    "period",
      +                                    "event",
      +                                    "report",
      +                                    "expiration",
      +                                    "scheduled",
      +                                    "observation"
      +                                  ]
      +                                },
      +                                "value": {
      +                                  "$ref": "#a2"
      +                                }
      +                              },
      +                              "required": [
      +                                "name",
      +                                "role",
      +                                "value",
      +                                "precision"
      +                              ],
      +                              "type": "object"
      +                            },
      +                            "maxItems": 8,
      +                            "type": "array"
      +                          },
      +                          "measurements": {
      +                            "items": {
      +                              "additionalProperties": false,
      +                              "properties": {
      +                                "name": {
      +                                  "$ref": "#a4"
      +                                },
      +                                "unit": {
      +                                  "$ref": "#a2"
      +                                },
      +                                "value": {
      +                                  "type": [
      +                                    "string",
      +                                    "number",
      +                                    "null"
      +                                  ]
      +                                }
      +                              },
      +                              "required": [
      +                                "name",
      +                                "value",
      +                                "unit"
      +                              ],
      +                              "type": "object"
      +                            },
      +                            "maxItems": 128,
      +                            "type": "array"
      +                          }
      +                        },
      +                        "required": [
      +                          "attributes",
      +                          "measurements",
      +                          "clocks"
      +                        ],
      +                        "type": "object"
      +                      },
      +                      {
      +                        "type": "null"
      +                      }
      +                    ]
      +                  },
      +                  "observed_at": {
      +                    "$ref": "#a2"
      +                  },
      +                  "period_end": {
      +                    "$ref": "#a2"
      +                  },
      +                  "position": {
      +                    "$ref": "#/$defs/c"
      +                  },
      +                  "put_call": {
      +                    "$ref": "#a2"
      +                  },
      +                  "record_id": {
      +                    "type": "string"
      +                  },
      +                  "report_period": {
      +                    "$ref": "#a2"
      +                  },
      +                  "reported_at": {
      +                    "$ref": "#a2"
      +                  },
      +                  "reported_value": {
      +                    "$ref": "#/$defs/c"
      +                  },
      +                  "share_class": {
      +                    "$ref": "#a2"
      +                  },
      +                  "source_kind": {
      +                    "type": "string"
      +                  },
      +                  "support": {
      +                    "additionalProperties": false,
      +                    "properties": {
      +                      "content_hash": {
      +                        "$ref": "#a3"
      +                      },
      +                      "document_id": {
      +                        "type": "string"
      +                      },
      +                      "json_pointer": {
      +                        "$ref": "#a2"
      +                      },
      +                      "text_span": {
      +                        "additionalProperties": false,
      +                        "properties": {
      +                          "end": {
      +                            "exclusiveMinimum": 0,
      +                            "maximum": 9007199254740991,
      +                            "type": "integer"
      +                          },
      +                          "start": {
      +                            "$ref": "#a0"
      +                          }
      +                        },
      +                        "required": [
      +                          "start",
      +                          "end"
      +                        ],
      +                        "type": "object"
      +                      }
      +                    },
      +                    "required": [
      +                      "document_id",
      +                      "content_hash",
      +                      "json_pointer"
      +                    ],
      +                    "type": "object"
      +                  },
      +                  "type": {
      +                    "const": "institutional_holding"
      +                  },
      +                  "value_scale": {
      +                    "$ref": "#a2"
      +                  }
      +                },
      +                "required": [
      +                  "record_id",
      +                  "source_kind",
      +                  "support",
      +                  "observed_at",
      +                  "period_end",
      +                  "reported_at",
      +                  "native_details",
      +                  "type",
      +                  "manager_cik",
      +                  "manager_name",
      +                  "accession",
      +                  "report_period",
      +                  "filing_date",
      +                  "cusip",
      +                  "figi",
      +                  "share_class",
      +                  "put_call",
      +                  "position",
      +                  "reported_value",
      +                  "value_scale",
      +                  "is_amendment",
      +                  "amendment_type"
      +                ],
      +                "type": "object"
      +              },
      +              "maxItems": 100,
      +              "type": "array"
      +            },
      +            "retained_records": {
      +              "$ref": "#a9"
      +            },
      +            "status": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "family",
      +            "status",
      +            "records",
      +            "retained_records",
      +            "matched_records",
      +            "omitted_records",
      +            "held_records",
      +            "freshness",
      +            "coverage",
      +            "limitations"
      +          ],
      +          "type": "object"
      +        },
      +        "maxItems": 1,
      +        "type": "array"
      +      },
      +      "generated_at": {
      +        "$ref": "#a1"
      +      },
      +      "historical_issuer_ownership_verified": {
      +        "anyOf": [
      +          {
      +            "const": false
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "issuer_refresh": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "backfill_from": {
      +            "$ref": "#a8"
      +          },
      +          "backfill_through": {
      +            "$ref": "#a8"
      +          },
      +          "filing_inventory_verified_at": {
      +            "$ref": "#a7"
      +          },
      +          "held_documents": {
      +            "$ref": "#a0"
      +          },
      +          "history_complete": {
      +            "type": "boolean"
      +          },
      +          "status": {
      +            "enum": [
      +              "not_required",
      +              "queued",
      +              "unavailable",
      +              "saved_only"
      +            ]
      +          }
      +        },
      +        "required": [
      +          "status",
      +          "filing_inventory_verified_at",
      +          "backfill_from",
      +          "backfill_through",
      +          "history_complete",
      +          "held_documents"
      +        ],
      +        "type": "object"
      +      },
      +      "limitations": {
      +        "$ref": "#ab"
      +      },
      +      "operation": {
      +        "const": "get_institutional_holdings"
      +      },
      +      "pagination": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "filters_sha256": {
      +            "type": "string"
      +          },
      +          "next_cursor": {
      +            "$ref": "#a2"
      +          },
      +          "next_offset": {
      +            "$ref": "#a9"
      +          },
      +          "offset": {
      +            "$ref": "#a0"
      +          },
      +          "returned": {
      +            "$ref": "#a0"
      +          },
      +          "scan_complete": {
      +            "type": "boolean"
      +          },
      +          "scanned_rows": {
      +            "$ref": "#a0"
      +          },
      +          "snapshot_hash": {
      +            "$ref": "#a2"
      +          },
      +          "snapshot_id": {
      +            "anyOf": [
      +              {
      +                "$ref": "#a6"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ]
      +          },
      +          "total_matching_records": {
      +            "$ref": "#a9"
      +          },
      +          "total_retained_records": {
      +            "$ref": "#a9"
      +          }
      +        },
      +        "required": [
      +          "offset",
      +          "returned",
      +          "total_retained_records",
      +          "total_matching_records",
      +          "next_offset",
      +          "snapshot_id",
      +          "snapshot_hash",
      +          "filters_sha256"
      +        ],
      +        "type": "object"
      +      },
      +      "query_binding": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "artifactId": {
      +            "$ref": "#a6"
      +          },
      +          "contentHash": {
      +            "$ref": "#a3"
      +          }
      +        },
      +        "required": [
      +          "artifactId",
      +          "contentHash"
      +        ],
      +        "type": "object"
      +      },
      +      "resource": {
      +        "const": "company_dataset"
      +      },
      +      "schema_version": {
      +        "const": "2"
      +      },
      +      "snapshot_captured_at": {
      +        "$ref": "#a7"
      +      },
      +      "sources": {
      +        "items": {
      +          "anyOf": [
      +            {
      +              "additionalProperties": false,
      +              "properties": {
      +                "capture_basis": {
      +                  "enum": [
      +                    "http_response_bytes",
      +                    "retained_export",
      +                    "retained_case"
      +                  ]
      +                },
      +                "content_hash": {
      +                  "$ref": "#a3"
      +                },
      +                "id": {
      +                  "$ref": "#a4"
      +                },
      +                "kind": {
      +                  "enum": [
      +                    "sec_disclosure",
      +                    "government_award",
      +                    "issuer_disclosure",
      +                    "research_input"
      +                  ]
      +                },
      +                "observed_at": {
      +                  "$ref": "#a1"
      +                },
      +                "publication_date": {
      +                  "$ref": "#a8"
      +                },
      +                "publication_precision": {
      +                  "enum": [
      +                    "instant",
      +                    "date",
      +                    "unknown"
      +                  ]
      +                },
      +                "published_at": {
      +                  "$ref": "#a7"
      +                },
      +                "raw_capture_hash": {
      +                  "$ref": "#/$defs/e"
      +                },
      +                "representation": {
      +                  "enum": [
      +                    "provider_json",
      +                    "sec_xbrl",
      +                    "visible_text",
      +                    "retained_research_case"
      +                  ]
      +                },
      +                "retained_record_hash": {
      +                  "$ref": "#/$defs/e"
      +                },
      +                "source_id": {
      +                  "$ref": "#a6"
      +                },
      +                "title": {
      +                  "type": "string"
      +                },
      +                "url": {
      +                  "$ref": "#a5"
      +                }
      +              },
      +              "required": [
      +                "id",
      +                "source_id",
      +                "kind",
      +                "title",
      +                "url",
      +                "published_at",
      +                "publication_date",
      +                "publication_precision",
      +                "observed_at",
      +                "content_hash",
      +                "raw_capture_hash",
      +                "retained_record_hash",
      +                "capture_basis",
      +                "representation"
      +              ]
      +            },
      +            {
      +              "additionalProperties": false,
      +              "properties": {
      +                "calendar_artifact_id": {
      +                  "$ref": "#a6"
      +                },
      +                "calendar_content_hash": {
      +                  "$ref": "#a3"
      +                },
      +                "content_hash": {
      +                  "$ref": "#a3"
      +                },
      +                "id": {
      +                  "type": "string"
      +                },
      +                "kind": {
      +                  "const": "stored_market_data"
      +                },
      +                "observation_count": {
      +                  "$ref": "#a0"
      +                },
      +                "observation_hashes_sha256": {
      +                  "$ref": "#a3"
      +                },
      +                "observed_at": {
      +                  "$ref": "#a1"
      +                },
      +                "providers": {
      +                  "$ref": "#ab"
      +                },
      +                "representation": {
      +                  "const": "reconciled_daily_bars"
      +                },
      +                "title": {
      +                  "type": "string"
      +                },
      +                "url": {
      +                  "$ref": "#a5"
      +                }
      +              },
      +              "required": [
      +                "id",
      +                "kind",
      +                "title",
      +                "url",
      +                "observed_at",
      +                "content_hash",
      +                "observation_hashes_sha256",
      +                "observation_count",
      +                "calendar_artifact_id",
      +                "calendar_content_hash",
      +                "representation"
      +              ]
      +            }
      +          ],
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "status": {
      +        "enum": [
      +          "available",
      +          "partial",
      +          "unavailable"
      +        ]
      +      },
      +      "ticker": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "schema_version",
      +      "resource",
      +      "operation",
      +      "ticker",
      +      "as_of",
      +      "generated_at",
      +      "status",
      +      "context",
      +      "snapshot_captured_at",
      +      "historical_issuer_ownership_verified",
      +      "data",
      +      "sources",
      +      "pagination",
      +      "limitations"
      +    ]
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "error": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "code": {
      +            "enum": [
      +              "unauthorized",
      +              "invalid_input",
      +              "entity_not_found",
      +              "entity_ambiguous",
      +              "outside_entitlement",
      +              "rate_limited",
      +              "data_unavailable",
      +              "insufficient_sample",
      +              "unsupported_security",
      +              "duplicate_request"
      +            ]
      +          },
      +          "message": {
      +            "$ref": "#a4"
      +          },
      +          "recovery": {
      +            "anyOf": [
      +              {
      +                "$ref": "#a4"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ]
      +          },
      +          "retryable": {
      +            "type": "boolean"
      +          }
      +        },
      +        "required": [
      +          "code",
      +          "message",
      +          "recovery",
      +          "retryable"
      +        ],
      +        "type": "object"
      +      }
      +    },
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
  2. Added

TDQS

A3.8/5.0
Behavior4/5

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

Annotations only declare readOnlyHint=false, openWorldHint=false, idempotentHint=false and destructiveHint=false, so the description must explain why a retrieval is not read-only — and it does: 'Uses account allowance or prepaid credit' discloses cost, and 'Current requests recheck stale mirror metadata; historical/pinned reads never switch snapshots' discloses a side effect and its pinning escape hatch. It also warns that 'Identifier and filing-join checks hold ambiguous records,' a real behavioral quirk. Rate-limit and error behavior remain unstated, keeping it below 5.

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?

The scope sentence is front-loaded and every sentence carries distinct information: filters, return typing, ambiguity handling, snapshot/staleness semantics, continuation, and billing. Some packing is dense to the point of opacity ('source support', 'native value scales remain explicit'), and the return-typing sentence adds little given an output schema exists, costing a point.

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?

This is a high-complexity tool — 21 parameters, 3 required, snapshot pinning, billing, and an output schema — and the definition covers the hard parts: continuation tokens, snapshot immutability, date-field distinction, and credit consumption. Return-value shape is legitimately delegated to the output schema. Missing are prerequisites for ticker resolution and any statement of result-set bounds, which is the only notable gap.

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?

At 21 parameters and 62% schema coverage, the description carries real burden and meets it: it names the filter axes (manager name or CIK, report period, filing dates, amendments, share class, shares versus PUT/CALL) and clarifies their meaning, notably that 'report dates differ from filing dates' and that 'native value scales remain explicit.' It does not clarify the roles of offset, limit, conversation_id or max_snapshot_age_hours beyond what the schema already states, so 4 rather than 5.

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 opening sentence names a specific verb and resource ('Retrieves reported institutional holdings') and bounds it ('for one ticker across supported retained 13F history'), so the agent can distinguish this from insider trades, options activity, or company facts siblings without opening the schema. It does not explicitly name a competing sibling or state a scope-exclusion the way a top-tier definition would, which keeps it at 4.

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?

Usage guidance is operational rather than selectional: it tells the agent to 'Continue with the returned snapshot ID/hash, as_of, filters and cursor or next_offset,' which is genuine when-to-do-what instruction for pagination. It never states when to prefer this tool over an alternative, nor any exclusions or prerequisites, leaving the choice between holdings and other company-data siblings implied by the resource name alone.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.