Surface Inventory Tool

What problem it solves

The surface-inventory tool provides a curated inventory snapshot for AI copilots. When an LLM needs context about "what the user has" (e.g., for a portfolio review or transfer suggestion), it calls this tool instead of constructing multiple resource fetches. The tool returns a compact, copilot-optimized view: positions, portfolios, and key metadata. It reduces latency and token usage for common copilot flows.

Input schema

{
  "participant_id": "string (optional) - Filter by participant; default: API key's default",
  "portfolio_ids": "array of strings (optional) - Limit to specific portfolios",
  "include_metadata": "boolean (optional, default true) - Include transferability, encumbrances"
}

If participant_id is omitted, the tool uses the default participant associated with the API key (or org context).

Output schema

{
  "positions": "array - Position summaries (id, portfolio, quantity, value, transferable)",
  "portfolios": "array - Portfolio summaries (id, name, position_count)",
  "total_value": "number (optional) - Aggregated value if available"
}

The format is flattened for easy LLM consumption. Full objects are available via resources if needed.

Idempotency

The tool is idempent. Read-only; repeated calls with same input return same results (subject to data changes).

Side effects

None. No writes or external side effects.

Required scopes

• positions:read
• portfolios:read

Safe and unsafe contexts

Safe for all contexts. Read-only. Suitable for sandbox and production.

Expected latency

Typically 150–500 ms. May aggregate multiple API calls; optimized for copilot use.

Example usage

Input: { "participant_id": "part_abc123", "include_metadata": true }

Output: { "positions": [...], "portfolios": [...], "total_value": "5000000" }

Common failure modes

• 401 Unauthorized: Invalid API key. Check credentials.
• 403 Forbidden: Missing read scopes. Add positions:read, portfolios:read.
• 404 Not Found: Participant not found. Verify participant_id.

Audit records emitted

DMTR API calls are logged (positions.list, portfolios.list). No separate MCP audit.