MCP Tool Catalog

This is every tool the InvesTeam MCP server exposes, one to one with a public API endpoint. Each tool validates its input, forwards your hfk_ key to exactly one /api/v1/** route, and returns that route's JSON verbatim. Seven tools are ship-first (always registered); three are gated and register only when their server-side flag is on. Output is decision-support analysis, not investment advice.

What tools does the InvesTeam MCP server expose?¶

The server exposes the brief loop, the point reads, an identity check, and — when gated flags are on — the live committee-run tools. Path-interpolated ids (session_id, question_id) are constrained to ^[A-Za-z0-9_-]{1,64}$, so a malformed or traversal id is rejected at the tool boundary before any upstream call. Tools marked gated are absent from the tool list until enabled.

What are the three result shapes?¶

Every tool returns one of three structured shapes you can branch on without exception handling. A success is the upstream API JSON verbatim (an object; for AI-output tools it includes a disclosure field). A not-ready sentinel is a poll tool's contractual 404 — it is not an error, so keep polling:

{ "ready": false, "session_id": "sess_abc123" }

An error is a structured failure, also surfaced as an MCP isError result, carrying a closed-set code (bad_request, unauthorized, forbidden, not_found, conflict, rate_limited, upstream_error, internal_error), a verbatim message, a request_id, and a retryable flag. On a 429 the API's Retry-After seconds ride as retry_after_seconds.

What does create_brief do?¶

create_brief submits a free-form investment mandate — a question, thesis, ticker, or portfolio question — and kicks off (or rejects) a brief session. It backs POST /api/v1/briefs.

• Inputs: input (string, 1–20,000 chars, required); idempotency_key (string, optional — one is synthesised if omitted, so a retry carries a stable key).
• Output: the brief response with a session_id and a status — rejected (off-mandate; read the message), needs_clarification / awaiting_answers (answer with answer_clarifications), or completed. The status enum is open: treat an unknown value as non-terminal and keep polling get_brief.

What does answer_clarifications do?¶

answer_clarifications answers the analyst's clarifying questions for a session. It backs POST /api/v1/briefs/{session_id}/answers.

• Inputs: session_id; answers (at least one item, each {question_id, selected_options?, custom_answer?} with custom_answer ≤ 5,000 chars); idempotency_key (optional). Combine selected_options and custom_answer freely.
• Output: another needs_clarification round (answer again) or a completed brief.

What does get_brief do?¶

get_brief fetches a session's current state and brief — for re-hydration, or to poll to a terminal status. It backs GET /api/v1/briefs/{session_id}.

• Inputs: session_id.
• Output: the brief response. Poll every ~2–3s until completed or rejected. A 404 here is not_found (a bad or foreign id), not not-ready — a brief that exists is always readable by its owner.

What does list_sessions do?¶

list_sessions lists the calling principal's sessions, newest-first. It backs GET /api/v1/sessions.

• Inputs: limit (optional, 1–200) and cursor (optional) — forwarded only once the API paginates; until then the full owner-scoped list returns.
• Output: {session_id, title, status, created_at} per session.

What does get_orchestration do?¶

get_orchestration fetches the committee and task plan for a session. It backs GET /api/v1/orchestrations/{session_id}.

• Inputs: session_id.
• Output: {session_id, status, committee[], tasks[]}. A 404 is not-ready (the plan is still in flight) — keep polling, no faster than the server's minimum interval or you get a rate_limited back-off.

What does get_analysis do?¶

get_analysis fetches the final red-teamed synthesis once the committee completes. It backs GET /api/v1/analyses/{session_id}.

• Inputs: session_id.
• Output: the synthesis payload. A 404 is not-ready ("no analysis yet — results still in flight") — keep polling every ~2–3s until the synthesis returns.

What does auth_whoami do?¶

auth_whoami confirms the principal and tier your key resolves to before you spend a kickoff. It backs GET /api/v1/auth/me.

• Inputs: none (the key only).
• Output: the profile ({uid?, email?, tier, …}); tier is the load-bearing field.

Which tools are gated?¶

Three tools register only when their feature flag is on, so an agent must not assume they are present — list the server's tools and branch on what is offered. They cover the live committee run:

• convene_committee — convenes the committee over a completed brief (creates the orchestration), backing POST /api/v1/orchestrations. Inputs: session_id; brief (the Master Investment Brief JSON, validated upstream); idempotency_key (optional). Output: {session_id, status, committee[], tasks[]}. This spends a full committee run — inspect the brief first.
• get_execution — polls committee execution progress (task statuses and findings), backing GET /api/v1/executions/{session_id}. Output: {session_id, status, subject, plan_summary, committee[], tasks[], latest_seq?} with status in running | partial | completed | failed (open enum). A 404 is not-ready.
• get_transcript — streams the deliberation transcript via a cursor, backing GET /api/v1/executions/{session_id}/transcript. Inputs: session_id; after (integer ≥ 0, the last seq consumed). Advance the cursor only forward; a 404 before the first turn is not-ready. Once get_execution is terminal, do one final read, then stop.

When a gated tool's flag is off, the tool is simply absent from the tool list — never a stub that returns an error. The gated tools flip on as their upstream gates clear, without changing any ship-first tool.

What is the disclosure passthrough?¶

Every tool that returns or acts on AI-generated analysis carries a legal disclosure. The disclosure object originates upstream on the public API and is passed through verbatim — the server never strips, truncates, or re-models it. The same sentence rides in each such tool's description so the obligation reaches your agent's context at wiring time:

You must surface this notice to your end users and must not remove or alter the disclosure field.

What's next?¶

For the submit→poll loop, cadence, and terminal states, see Agent Patterns. To connect, see Connect to Claude or Connect Other Clients. The same endpoints in plain HTTP are the Briefs reference and the rest of Integrate.