Query Registry Tool

What problem it solves

The query-registry tool lets an LLM search Dark Matter data using natural language. Users ask questions like "What positions do I have in SPV LLC?" or "Show me transferable positions over $1M." The tool translates the query into DMTR API calls and returns structured results. It eliminates the need for users to know API filters or query syntax.

Input schema

{
  "query": "string (required) - Natural language query",
  "limit": "number (optional, default 50) - Max results",
  "scope": "string (optional) - portfolio | participant | position | all (default all)"
}

The query is free-form text. The scope narrows the search to a specific entity type. The tool uses semantic parsing to extract filters (e.g., portfolio name, amount thresholds) from the query.

Output schema

{
  "results": "array of position/portfolio/participant objects",
  "summary": "string - Brief natural language summary",
  "total_count": "number - Total matching records"
}

Results match the DMTR API object schemas. The summary is a short description suitable for the LLM to incorporate into its response.

Idempotency

The tool is idempotent. It performs only read operations; repeated calls with the same input return the same results (subject to data changes in Dark Matter).

Side effects

None. The tool does not modify Dark Matter or any external state.

Required scopes

• positions:read
• portfolios:read
• participants:read (if scope includes participants)

Safe and unsafe contexts

Safe for all contexts. Read-only; no risk of data modification or destructive actions. Suitable for sandbox and production.

Expected latency

Typically 200–800 ms depending on query complexity and result size. The tool may make multiple API calls internally (e.g., list portfolios then filter positions).

Example usage

Input: { "query": "positions in SPV LLC over 100000", "limit": 10 }

Output: { "results": [...], "summary": "Found 5 positions in SPV LLC with value over $100,000.", "total_count": 5 }

Common failure modes

• 401 Unauthorized: Invalid or expired API key. Check credentials.
• 403 Forbidden: API key lacks required scopes. Add read scopes.
• Parse failure: Query too ambiguous. Suggest user rephrase or add filters.
• Rate limit: Too many requests. Retry with backoff.

Audit records emitted

Each DMTR API call is logged. Audit events include: positions.list, portfolios.list, participants.list (as invoked). No separate MCP-level audit; DMTR API audit applies.