InvestMCP

Overview Schema Source Related Servers Discussions Admin

export_portfolio_dataset

Export an auditable portfolio dataset by freezing a local copy and paging through transactions, realized P&L, holdings, or NAV history as JSON or CSV.

Instructions

Freeze an auditable portfolio dataset locally, then return small pages.

Only for an explicit request to export, save or freeze a dataset. A dated portfolio value series is get_portfolio_returns(include_series=true), which stores nothing.

Transaction exports default to YTD (365 days with end_date alone); pass start_date (e.g. 2024-01-01) or period="ALL" for older history.

Writes only local dataset copies and never places orders or uploads data. First call (no dataset_id) captures normalized inputs through existing engine paths. Later calls supply dataset_id and next_cursor as cursor; they read only the frozen copy, with no provider/FX refetch. Returned manifest identifies the original dates and filters; replay does not reapply collection parameters. IDs are content hashes. The latest 20 datasets are retained; expired/unknown IDs return DATASET_EXPIRED and never silently rebuild. Start a new first call explicitly to collect changed inputs. Missing money stays null with a status.

JSON rows have record_type, row_id, data. CSV has those first two columns and data_json (canonical JSON preserving nested fields, null and statuses). Supporting holdings, cash, source coverage, cost FX, quantity breaks and NAV components are paged audit records. Manifest descriptors name their row types; read every page to reconstruct/hash the entire dataset. Totals sum frozen input money by type/currency; reporting summaries retain their stated period. Account IDs are opaque keyed hashes. Human account labels are retained only when already exposed, and raw broker payloads/credentials are excluded.

Args: dataset: transactions, realized_pnl, holdings, or nav_history period: reporting period (default YTD); explicit ISO dates override it start_date: ISO YYYY-MM-DD; realized inputs include earlier basis history end_date: ISO YYYY-MM-DD. Holdings export is current, not historic backfill dataset_id: frozen ID for replay; omit only for a new collection cursor: opaque next_cursor from the preceding page; requires dataset_id format: json or csv; both carry the same typed audit rows page_size: 1–200, additionally limited to 64 KiB of row data per page account: existing account filter; nav_history requires all accounts symbol: optional existing symbol filter; not applicable to nav_history input_snapshot_ids: nav_history only, exact E-store versions; bounds use their dates when no explicit dates are supplied

Input Schema

Name	Required	Default
`cursor`	No
`format`	No	json
`period`	No	YTD
`symbol`	No
`account`	No	all
`dataset`	Yes
`end_date`	No
`page_size`	No
`dataset_id`	No
`start_date`	No
`input_snapshot_ids`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 24, 2026

TDQS

A5/5.0

Behavior5/5

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

Although annotations already cover safety and openness, the description adds substantial behavior: local-only dataset writes, no orders or uploads, frozen-copy replay with no provider/FX refetch, latest-20 retention, DATASET_EXPIRED on unknown IDs, and privacy handling for account IDs and raw broker payloads. These details materially improve invocation safety and expectations beyond the 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?

The description is long but proportionate to an 11-parameter paged export tool with retention and replay behavior. It is front-loaded with the core action and usage constraint, then organized into readable paragraphs and a structured Args section.

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?

Even with an output schema present, the description sufficiently covers paging, manifest behavior, row formats, hashing, retention, and error semantics. Given the tool's complexity, schema size, annotations, and output schema, an agent has enough information to call it correctly.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must carry parameter meaning; the Args section explains all 11 parameters, including defaults, filters, page limits, cursor requirements, and dataset-specific constraints. It adds clear semantics beyond the raw schema, such as page_size being capped by 64 KiB per page and input_snapshot_ids applying only to nav_history.

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 first sentence states a specific verb and resource: "Freeze an auditable portfolio dataset locally, then return small pages." It also explicitly distinguishes this from the adjacent get_portfolio_returns(include_series=true) use case, which stores nothing.

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?

It gives a clear inclusion criterion: "Only for an explicit request to export, save or freeze a dataset." It names the main alternative and when to use it, and it clarifies default date behavior and when to use start_date or period="ALL".

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