Prism MCP foundation

What this skill teaches

Workflow

1. 1

   Start with get_prism_workspace_context, using the essentials profile when stable Project ids are already known.

2. 2

   Use get_agent_context_pack or search_library to retrieve the smallest useful evidence set.

3. 3

   Follow Prism's recommended tools, then fetch precise sources or stable chunks before making factual claims.

4. 4

   For multi-step work, report meaningful progress and finish with the evidence and resources used or created.

Tool routing

Safety boundaries

---
name: prism-mcp
description: Use when working with a user's Prism Projects, source-backed knowledge, Writing, Markets, or another MCP-connected Prism workflow.
---

# Prism MCP

Prism is the user's authorized knowledge layer. Use Prism MCP to retrieve saved sources, evidence, artifacts, and received Email before answering. The external AI client remains the orchestrator.

## Helping someone connect for the first time

Use plain language and one step at a time. Call the external client an “AI app” and explain that a Project holds files, links, and notes about one topic. Point users to https://app.tryprism.xyz/integrations/mcp/setup and ask them to choose their app. Do not request passwords or connection tokens in chat. Explain account restrictions using the provider requirements linked there.

After setup, ask the app to summarize a named file in a selected Project and include a source link. A successful sign-in is not proof that the file was read. If access fails, check source readiness, selected Projects, and whether Prism is enabled in the conversation. Never claim a connection is working without a successful read. Explain that the AI provider receives material it reads and that users can remove access in Connections. Keep technical tool names in diagnostics unless the user needs them.

## Project Agent specialist
Use get_project_agent_availability before asking whether paid Project Agent synthesis is available. It reports the enforced concurrent-run allowance and does not estimate a charge. Ask only with both knowledge:read and the explicitly authorized threads:run scope. ask_project_agent answers a Project question from existing authorized evidence with citations and gaps. Supply projectId, question and a unique requestId; reuse that requestId for transport retries, and conversationId for follow-ups. list_project_agent_conversations returns only the caller's private history and uses nextCursor pagination; get_project_agent_conversation reads one private conversation. fork_project_agent_conversation creates a new private branch only after its source run finishes. Supply a unique requestId and reuse it on a transport retry to receive the same branch. If pending, poll get_project_agent_run at pollAfterMs; cancel_project_agent_run stops it. Asking uses the caller's AI usage and saves a private conversation. It cannot browse or edit project content. Prefer get_agent_context_pack/search_library when you want raw evidence and own the reasoning.

## Connection

- Transport: Streamable HTTP.
- Production endpoint: https://app.tryprism.xyz/api/mcp.
- Free includes one read/write authorized AI client, up to 100 semantically indexed sources, and 100 accepted MCP calls per UTC calendar week. Standard includes five authorized clients; Pro includes 25. Standard and Pro include unlimited semantic indexing and accepted MCP calls. New connections still default to knowledge:read; sensitive and write scopes require explicit authorization, are never auto-granted, and remain subject to Prism's plan, Project-access, confirmation, and safety limits.
- research:read is a legacy alias for knowledge:read and grants no additional access.
- Direct Prism API keys require a paid plan. Every plan can explicitly authorize currently exposed MCP scopes, including memory, Email, finance, publishing, portfolio, watchlist, calendar, threads:write, threads:run, and other writes. Model-provider keys for Prism Chat and Work are a separate setting available on every plan. email:read and calendar:read are privacy-sensitive and are never auto-granted with future read scopes.
- Write tools are authorized when their explicit connection scopes are granted; they do not depend on an opt-in deployment flag. A deployment may set PRISM_MCP_WRITE_TOOLS_ENABLED=false only as an emergency kill switch. Prism advertises a compact server-authorized catalog for ordinary owned-Project connections and keeps granular actions behind discover_prism_actions plus execute_prism_action. Shared-Project connections instead receive only direct granular actions that pass the delegated-action policy; generic action gateways, research bundles, monitor management, and destructive tools are not delegated. External hosts should call verify_prism_host_capabilities with their exact callable action names. Treat only get_prism_workspace_context.tools.verifiedCallableNames as immediately available; authorizedNames may include actions that require a host refresh. A host may retain a separately approved or frozen action snapshot. If hostExposureVerified is false, follow the returned recovery guidance, refresh or rescan actions, enable them for the agent, publish the host configuration when required, start a new conversation, and verify again.
- Preferred auth: OAuth discovery when the AI tool supports it. Removing a configured scope is immediate, but additions require OAuth reauthorization before they become active; reauthorization retains previously issued scopes and adds newly approved scopes.
- Manual auth: Authorization: Bearer prism_mcp_... or an environment variable such as PRISM_MCP_TOKEN.
- Treat Prism tokens and OAuth grants as secrets. Do not print, store, or commit them.
- Shared Projects use the collaborator's own Prism MCP connection. They must be explicitly selected in that connection's Project picker; an empty folder allow-list means all Projects owned by the collaborator and never includes Projects shared by someone else. Effective access is the intersection of client scopes, selected Projects, membership role, and the owner's AI grant. Recheck the live grant on every call.

## Workflow

Start with get_prism_workspace_context for almost every task. Use profile "essentials" when stable folder ids are already known; use profile "full" when recent objects, writing context, or richer routing hints are needed. Native JSON lives in structuredContent; the text content is only a compact fallback summary. On an external host, verify_prism_host_capabilities establishes whether the current host can actually invoke the authorized default tools. Use discover_prism_actions only when the workflow tools need a granular operation; use get_prism_action_schema to load its exact payload contract before constructing a preview or execution payload.

Route quickly:

- Workspace orientation: call list_projects when a Project id is not already known, get_project for an exact Project's revision and overview policy, and get_project_access to understand the caller's effective role, personal favorite revision, agent-access policy, and safe sharing summary. Owners may see member roles and public-link follower counts; collaborators receive only their own access summary. Never expect invitation or public-link tokens. Use set_project_preference only with actor.preferences.updatedAt from that access read. Use reorder_projects only with the complete favorite list and favoriteOrderingRevision returned by list_projects. Use list_project_folders only for bounded structure discovery. Then use get_prism_workspace_context with profile "essentials" when possible, followed by get_agent_context_pack or search_library.
- Source-to-research update: use ingest_research_update. Preview the immutable raw capture, clean source, F/M/E/J observations, Research Delta proposals, watchlist transitions, affected models/articles, and evidence links. Commit only the approved preview. The workflow never applies the canonical thesis or changes a published article.
- Published writing revision: use revise_writing_object to resolve a draft or post, read a full published revision context, fork one private revision draft, patch stable blocks, attach exact citations, and update cover provenance. Always preview and commit writes. A person reviews and republishes in Prism.
- Monitoring: use manage_project_monitor to create, update, pause, run, inspect, acknowledge, and brief from unified Project monitors. Preserve the distinction between new, repeated, stronger, completed, slipped, contradictory, and thesis-neutral information.
- Research changes: use propose_research_delta for review-only delta creation, revision, inspection, and links. Never apply a canonical thesis through MCP.
- Models and recaps: use run_research_model for persistent scenario calculation and generate_project_recap for time-bounded Project change summaries. Treat assumptions and observations as learned context and retrieve their exact evidence before citing them.
- Writes: workflow writes use preview, commit, a durable operation log, and a declared undo or compensation path. Reuse one idempotency key only for retries of the same intent. Never bypass an optimistic expectedUpdatedAt or expectedVersion conflict.
- Access boundaries: honor workspace.restrictions.folderGrantMode. For new or re-consented connections, a selected subtree root includes its descendants; legacy exact grants include only the listed folders. Never treat a raw root id as proof that an unrelated folder is authorized.
- Shared Project boundaries: use Project UUIDs rather than name-only folder paths. AI read grants expose only shared research content, not any member's Email, personal memory, chats, portfolio, drafts, or integration settings. AI write grants permit only allowlisted non-destructive Project content tools and explicitly scoped Research Thread runs; they never permit deleting/trashing, root management, publishing, monitoring configuration, portfolio changes, or Research Delta or Research Thread approval/dismissal/application. Calls and metered Thread runs belong to the collaborator while new storage and indexing consume the Project owner's allowance.
- Durable research packet work: create or choose a Project with create_library_folder. A new top-level Project automatically receives a title-based inbound Email address in emailAddress; nested folders return emailAddress: null. Link companies with add_library_folder_company, configure additional or replacement Email aliases only when requested, add RSS feeds, YouTube video transcript sources, supported local file sources, or one-time web imports, then create notes up to 200,000 characters each, artifacts, thesis review proposals, graph relationships, and a Project Canvas packet with create_library_canvas without publishing, sending email, trading, or portfolio mutation. Use update_project_overview with library:edit and the latest Project updatedAt only when the user asks the agent to revise an AI-managed overview, aiOverviewEnabled is true, and descriptionEditedAt is null. Never replace user-written overview text. Use update_project_metadata with library:manage for Project name/icon changes. The hidden update_library_folder compatibility alias remains callable only with both library:manage and library:edit and uses preview, operationId, commitToken, and the same AI-overview protection; new callers should not discover or select it. Folder lifecycle changes use library:manage: move_project_folder with fresh source and destination revisions for same-Project hierarchy changes, move_project_items and trash_project_items through their own preview, operationId, and commitToken flow with fresh item/destination revisions, trash_project for normal recoverable top-level Project deletion, list_project_trash and restore_project_trash_item for recovery, and archive_library_folder for reversible removal from active views. Direct trash_project, archive_library_folder, restore_project, restore_project_trash_item, and delete_library_folder previews require an idempotencyKey and return an operationId and commitToken. Commit uses only that saved preview and subtree binding, rechecks Project ownership and the trash purge deadline where applicable, rejects intervening changes or expired batches, and replays a completed result rather than applying lifecycle work twice. delete_library_folder additionally requires the separate high-risk library:purge scope, explicit confirm: true, and the latest expectedUpdatedAt.
- Organization planning: use plan_project_organization for a bounded, read-only grouping proposal. It never creates folders or changes any source. After user review, create a destination folder explicitly and use move_project_items with current item and destination revisions.
- Folder moves: move_project_folder defaults to preview. Direct preview requires an idempotencyKey and returns operationId plus commitToken; direct commit must carry those and the preview commitBinding for every source-subtree revision as well as current source and destination revisions. execute_prism_action persists the binding automatically.
- Archive effects: archive_library_folder is reversible and clears owner folder favorites. It does not silently cancel jobs, disable schedules, revoke inbound Email, or delete membership/link grants. Archived Projects are nevertheless unavailable to collaborators until an owner restores them, so inspect and handle those independent services explicitly.
- Project-specific discovery: get_project can selectively return metadata, overview policy, active-subtree counts, current capabilities, and Project service totals without loading evidence. get_project_capabilities separates authorizedActionIds from currentlyExecutableActionIds; allowedActionIds is the compatibility alias for the latter, and each action contract includes its current availability. Pass projectId to discover_prism_actions when choosing an action for one Project. capabilityFamily and intent narrow the catalog through current role, grant, scope, and shared-Project policy, but a later commit is always reauthorized.
- Project metadata images: update_project_metadata accepts only the current Project's validated Prism image reference. Upload or select the image in Prism first; do not submit arbitrary external URLs.
- AI-managed overview: update_project_overview preserves AI-managed provenance, so it may be refreshed when its Project is current. It still refuses any Project with a human descriptionEditedAt value.
- Overview proposals: use propose_project_overview for an evidence-backed draft when a Project has a human overview or the user asks for review. Use list_project_overview_proposals and get_project_overview_proposal to inspect bounded proposals and their cited source IDs. Proposals are version-bound only; review and application remain first-party and human authorized.
- Project change feed: list_project_changes uses a durable activity sequence and retains events for 30 days by createdAt. Use nextCursor for older history in descending order. Save resumeCursor from the first history page, then pass it as sinceCursor to read newly committed changes in ascending order; continue a multi-page forward scan with nextSinceCursor. Non-tombstone events include a Project detailLink that the destination reauthorizes; tombstones intentionally omit it and withhold historical metadata. When resyncRequired is true, discard the cursor, re-read get_project and get_project_status, then begin a fresh change cursor.
- Project setup templates: use plan_project_setup to create a pinned, versioned structure-only plan, then have the user review it before applying with apply_project_setup through preview and commit. Direct calls require a fresh idempotencyKey for preview and the returned operationId plus commitToken for commit; Prism pins the planId, template, version, and folder inputs in the saved request and replays a fully completed result on retry. Every versioned template step has a durable child operation containing its stable stepId, folderId, and created/reused disposition. Folder creation and that child checkpoint commit together. After a partial failure, preview again with the same inputs and idempotencyKey to receive a fresh token; Prism replays completed step records and retries incomplete steps. The initial template creates or binds direct child folders only; it never copies content, memory, sharing, credentials, schedules, or external communication.
- Project creation: create_library_folder requires an idempotencyKey. Reuse the same key only to recover an interrupted response for the exact same name, parent, and description; Prism commits the folder, any top-level email alias, and its recorded MCP result together, then replays that result instead of provisioning a duplicate. User-facing starting templates for study, research, personal work, and investing are ordinary Project folders; they never change authorization or create durable memory.
- Knowledge repair: use plan_project_knowledge_repair after get_project_knowledge_health to distinguish stale derived indexes from source failures. Review a selected stale-index plan, then call request_project_knowledge_repair with a fresh idempotencyKey for preview. Direct commit requires the returned operationId and commitToken and uses only the saved file selection and revisions. Source failures require user review and source-specific recovery.
- Research question: get_agent_context_pack first. Pass a concise task, activeObjectIds when the user is already viewing Prism objects, and a selected-context token budget. Prism inherits the MCP transport session (and REST request id) when sessionId is omitted, so supply one only when deliberately correlating another workflow. Use profile "essentials" for fast orientation, "standard" by default, and "deep" for cross-source synthesis. maxTokens takes precedence over legacy limit and budgets recalled content, not the fixed JSON envelope. Inspect contextRunId, contextBlocks, evidence, observations, models, recommendedTools, tokenUsage, responseTokensEstimated, and trace; then use get_library_content_chunk for an exact stable citation or search_library with mode "chunks" plus get_library_file_chunk for a legacy file chunk.
- Research Threads: use list_research_threads before creating a durable hypothesis or starting work. Read a selected case file with get_research_thread. Use create_research_thread, add_research_thread_evidence, and propose_research_thread_revision only for durable user-requested changes. threads:run starts bounded, metered Prism model work: discover_project_threads scans a Project and run_research_thread deepens, verifies, red-teams, or refreshes one Thread. Both return runId, status, and pollAfterMs. Poll get_research_thread_run at that cadence until completed, failed, or cancelled. Only the exact MCP client that started a run may call cancel_research_thread_run. Never treat a completed run as human approval.
- Knowledge health: use get_project_knowledge_health before treating a no-result search as a retrieval-quality failure. It distinguishes recorded semantic coverage from verified current-revision coverage, reports active/delayed/failed/stale indexing, and counts successful allowlisted MCP retrievals attributed by Project scope or a returned Project source.
- Memory handoff: export_project_memory is owner-only and returns a full portable bundle by default: eligible shared memory bodies, owner research checkpoints, the active shared research brief, dependency metadata, checksums, and up to five explicitly selected bounded source binaries. Client-private and forgotten records stay excluded. Use format manifest for a lightweight revision inventory. preview_project_memory_import accepts the full export shape and is owner-only and review-only. It checks records for collisions, current evidence dependencies, and suppressed memories; source binaries remain export-only. Imported records remain proposals until the Project owner reviews them in Prism. These tools do not approve memory or change capture policy.
- Workspace memory: explicitly authorized memory:read allows bounded workspace memory to inform get_agent_context_pack and list_workspace_memories; it is never a default or future-read auto-grant. Without it, do not assume access to personal, ticker, or client-specific procedural memory. List memory first when a correction or deletion needs a stable id. Use remember_workspace_memory only when the user explicitly asks Prism to retain a durable fact, preference, procedure, open question, or source preference. Shared memories can inform authorized agents; client scope is only for procedural_preference and is bound server-side to the current client. A semantic_fact requires at least one approved evidenceRef. Use correct_workspace_memory when the user supplies a correction. Use forget_workspace_memory only for a specific memory id with confirm true: it purges the memory content, embeddings, and evidence, invalidates derived models, retains only a non-content audit fingerprint, and never deletes canonical source content. Keep transient task state in the current context run instead of durable memory.
- Project/source discovery: call get_library_taxonomy when classification matters; it returns the fixed content categories and allowed upload formats separately from sourceKind and tags. Then use search_library with mode "titles", "text", or "chunks" plus sourceKind/tags filters. Titles and text tokenize multi-word queries. Chunk mode searches stable indexed evidence across files, documents, artifacts, and canvases; inspect coverage, evidenceSufficient, abstentionReason, retrievalSignals, and location before asserting that Prism has relevant evidence. File metadata and citations include contentCategory; cite originalUrl when present and otherwise libraryUrl.
- Source organization: use create_library_tag for reusable custom labels and rename_library_tag/delete_library_tag only for custom tags. Use patch_project_item_tags for an atomic, versioned add/remove tag patch across sources in one Project. Start with mode "preview" and a unique idempotencyKey; inspect each before/after tag set, then commit only with that operationId and commitToken. Prism reuses the exact preview selection and revisions, creates tag-catalog entries only on commit, and replays a completed retry. tag_library_sources remains for legacy add/remove/replace clients. Source kinds describe what an item is; tags describe why it matters.
- Web sources: use import_library_web_source only for a news article, company press release, or readable web page. Pass sourceKind/tags explicitly when known; otherwise Prism infers them. Prism checks that its bounded extractor can read the page before creating a Library source. If it rejects the URL, report the reason and use the publisher's readable canonical page, a supported upload, or user-supplied text as appropriate; do not retry the same blocked or login-gated URL or create a note that copies inaccessible page content.
- Project notes: use create_library_note only for original or user-supplied text with no canonical readable URL. Pass contentFormat explicitly: markdown creates a rendered .md note with headings, emphasis, lists, links, quotes, tables, and code; plain_text creates a literal .txt note. Use Markdown links instead of bare URLs where readability matters and do not send raw HTML. Put the display title in title and do not repeat it as a body # heading. Prism normalizes a supplied .md, .markdown, or .txt extension to the selected format. If contentFormat is omitted, a .txt title infers plain_text and every other title defaults to markdown.
- Email: use list_email_addresses and list_email_messages to orient, then get_email_message only for a selected received message. email:read is explicit and privacy-sensitive. Use update_email_messages for reversible read, star, label, archive, trash, and restore actions; it cannot permanently delete. Trusting a sender creates no automation unless upsert_email_sender_rule configures labels, archive, or one Project auto-save. save_email_message_to_library requires both email:read and library:write, accepts an edited title/body, tags, selected attachments, and archiveAfterSave, and is idempotent per message and target Project.
- Project files and media: get_library_file returns contentCategory, mediaKind, mediaUrl, librarySourceUrl, sourceUrl, and bounded contentText when available. For uploaded binary bytes, call get_library_media after reading the file; it returns authorized bytes in bounded ranges, with offset continuation for larger videos and expectedUpdatedAt protection after the first range. Use upload_library_attachment when the host exposes a first-class chat file and pass it in the required top-level `file` field; Prism applies bounded, MIME-checked ingestion and can normalize host application/octet-stream metadata when the declared MIME, extension, and detected signature validate. Otherwise use upload_library_file_source for supported local PDFs, documents, spreadsheets, images, MP3 audio, or videos; declare contentCategory and mimeType and provide exactly one of fileBase64 or dataUrl. The server accepts up to 15 MB decoded bytes, but a connected AI host may impose a lower tool-payload or attachment limit. A chat attachment is not automatically available as bytes to every host: if the host cannot expose it, ask the user to upload it in Prism or provide a host-readable file. The declared category, extension, and MIME must agree after any validated octet-stream normalization. upload_library_media_source remains compatible for existing image/video clients. For update_library_file_metadata descriptions/tags/renames, first read the latest updatedAt, then preview with a unique idempotencyKey and commit only with its returned operationId and commitToken. Prism pins the exact metadata/revision, adds requested catalog tags and its durable indexing handoff inside the commit transaction with the file CAS and operation checkpoint, and replays a completed retry. Its description is searchable metadata and never replaces source text. For update_library_file_content, preview with a unique idempotencyKey after reading the latest revision; it validates access, editability, and the 1MB limit without changing the body. Commit only with that operationId and commitToken. Blob upload remains outside the database transaction and may leave an orphan-safe private blob if the commit fails, but after Blob persistence the file revision update, durable indexing handoff, and operation checkpoint commit together and a completed retry replays the saved result. Use replace_library_media_source only to replace uploaded image/video bytes.
- Direct Project source reads: get_library_file, get_library_file_text, and get_library_document default to compact output and can return up to 100,000 characters when maxCharacters is requested.
- Long PDFs, filings, transcripts, notes, imports, and web captures: search_library with mode "chunks", then get_library_content_chunk when the result has a stable library_content_chunk id; use get_library_file_chunk for legacy file chunks. Prefer chunk reads over capped full-text reads. Treat evidenceSufficient false as an abstention, distinguish incomplete indexed coverage from no relevant evidence, and use page/heading/sheet/slide location metadata when present.
- Inputs: top-level Project creation automatically provisions one inbound Email address under library:write. Use create_email_address with email:manage only for a personal address or an explicit replacement/legacy Project alias. Use remove_project_company only to unlink one known Project-company link: start with a current expectedFolderUpdatedAt, mode "preview", and a unique idempotencyKey, verify the exact link impact, then commit with its operationId and commitToken. It never deletes the company, evidence, or watchlist. Use add_library_rss_source for standalone RSS/Atom feeds, preview_youtube_transcript_source then import_youtube_transcript_source for YouTube video sources with transcripts, upload_library_file_source for supported local files, and import_library_web_source for one-time web imports. YouTube import saves a transcript and privacy-enhanced player URL under Videos, then queues search indexing in the background; repeated default-language imports of the same video into one Project reuse the existing source. It does not download audio, create MP3 files, or import arbitrary websites. File upload never fetches arbitrary remote files or videos. When the user asks to sign up for newsletters or forwarded content, return the Prism address for use in a separately authorized external browser/signup flow. Prism MCP cannot submit forms, click confirmation links, navigate links automatically, send email, revoke an address, or permanently delete messages.
- RSS source edits: update_project_rss_source changes only a feed title or enabled state. Start with mode "preview", the current source updatedAt, and a unique idempotencyKey; verify its exact before/after impact, then commit with the returned operationId and commitToken. It does not queue a foreground fetch or remove saved evidence. RSS refresh: refresh_library_rss_source first previews the authorized enabled source and queued durable-job effect. Start mode "preview" with a unique idempotencyKey, then commit only with its returned operationId and commitToken. repair_library_rss_source defaults to preview, which shows normalized URL and any feed-consolidation impact. For granular repair, start mode "preview" with a unique idempotencyKey and commit only with its returned operationId and commitToken; Prism retains the exact repair binding. A repair's source mutation, selected durable refresh-job handoff, and operation checkpoint commit together, while the worker's external feed fetch remains asynchronous and may still fail. Either may queue a refresh, and the durable job dedupe key coalesces retries. Poll get_project_jobs with kinds ["rss"] for status and results; do not wait for external feed fetching in the tool call.
- Company work: get_company_research_context, then get_company_thesis, get_company_claims, get_thesis_reviews, and source chunk tools. For SEC-only annual financial history, use get_sec_financial_model with knowledge:read; it is source-rich Company Facts data and does not include Yahoo or saved workbook assumptions. For a caller-owned Google Sheets model, use list_financial_models and get_financial_model with knowledge:read. Those tools are read-only and return status plus a nextAction web URL for human workbook creation, review, recovery, or update application. Never treat nextAction as write authorization. The existing mixed market financial-history endpoint may include Yahoo-backed values and follows its own market-data contract.
- Draft writing: prefer revise_writing_object for an existing draft or published post. Use get_article_drafts or create_article_draft for legacy direct draft work. Both accept an optional authorized Project folderId; omit it for legacy global Writing Studio behavior. New drafts may be articles, essays, reports, or newsletters. For AI-generated prose, prefer version-safe block patches or update_article_draft contentText with Markdown. Read first and pass expectedUpdatedAt, or use force true only for explicit one-writer agent workflows.
- Source review: list_library_site_monitor_items and list_library_rss_items with includeDescendants true to aggregate authorized Project folders. Filter reviewState by pending, saved, or dismissed and use the returned subjectFolder. Save only material signals; dismissed signals stay reviewable.
- Published posts: get_published_posts with filters, then get_published_post_evidence_health for a selected post.
- Portfolio work: list_portfolios first; use get_portfolio_exposure only when exposure details matter. Filter by folderId for one authorized Project or by tickers when useful, and pass includePrices false when live pricing is unnecessary. Treat nullable price, cost, purchase date, return, and exposure fields as unknown; inspect coverage before summarizing totals.
- Markets ticker watchlists: use list_watchlist_companies, then create_market_watchlist, update_market_watchlist, add_market_watchlist_company, remove_market_watchlist_company, or delete_market_watchlist when the connection has explicit watchlist:write. A watchlist-only task does not require get_prism_workspace_context or knowledge:read. Read the latest updatedAt before renaming; permanent watchlist deletion requires confirm true. These tools only change Prism tracking and never place trades or delete saved company research.
- Project watchlists: use list_project_watchlist_items with any authorized folder in the Project, then get_project_watchlist_item for the immutable timeline. Use get_project_watchlist_home_selections to read the viewing member's personal Home state and set_project_watchlist_home_visibility to idempotently add or remove only this MCP client's own selection; it cannot remove a human pin or hide Prism AI suggestions. Project watchlist writes also require explicit watchlist:write. Read the latest updatedAt before create/update/append/archive/restore/delete, use idempotencyKey for retries, use the latest orderVersion for a complete reorder, and pass confirm true for permanent deletion. Attach authorized Project evidence or a URL when an agent observation has support. Watchlist edits are monitoring metadata only: never treat them as permission to overwrite thesis fields, claims, catalysts, risks, or research-agenda rows; use Research Delta proposals for consequential thesis changes.
- Calendar: use list_calendar_events for a bounded date window and optional Project/company/type/status filters, then get_calendar_event before editing. calendar:read and calendar:write are explicit scopes. All-day events use startDate/endDate; timed events use startsAt/endsAt and an IANA timezone. Create or update earnings, guidance, targets, milestones, investor days, conferences, regulatory, product, capital-allocation, macro, or custom events with importance, date confidence, implications, preparation notes, outcomes, company links, and authorized sources/documents/articles/artifacts/URLs. Read the latest updatedAt before updating. Never call delete_calendar_event without the user's explicit approval; it requires confirm true and the latest updatedAt, and deletion remains in immutable history. Calendar events are scheduled dates, not a substitute for recurring Project watchlist monitoring.
- Visual artifacts: use prepare_chart_table_artifact for raw CSV, TSV, Markdown tables, or JSON rows; use plan_visualization_artifact for richer dashboards or custom runtimes; validate_visualization_artifact, then create_artifact and insert_article_visual_block for article placement, or attach_article_artifact_embed for simple start/end attachment. Native table column labels/string cells and chart x-axis category/display labels support safe inline Markdown: **bold**, *italic*, ~~strikethrough~~, `code`, and [links](https://example.com). For chart display names use labels: { xAxis?, series?: { [yKey]: label } } and keep y-series values numeric. Raw HTML and block Markdown are not interpreted in these native labels. create_library_artifact, create_article_artifact, and create_visualization_artifact remain compatibility tools. For live stock/valuation visuals, call list_market_data_metrics and resolve_market_data_bindings first.
- Knowledge graph: list_library_relationships with source/target/relationshipType filters before creating duplicates. Use create_library_relationships when connecting one output to several nodes.
- Canvas work: list_library_canvases, get_library_canvas, preserve user-authored layout, then update_library_canvas only with the latest expectedUpdatedAt. Use dryRun true to inspect node/edge diffs; pass allowRemovals true only when removals are intentional.
- Multi-step workflows: call report_mcp_workflow_progress at the start, during major steps, and on completion/failure so the user can see progress in Prism. On completion, include outcome (resolved, partial, no_result, corrected, failed, or abandoned), the contextRun id/profile/token usage, evidence consulted, resources created or updated, and any explicit memory correction. Do not treat a successful transport call as proof the workflow found a useful result.

Preserve evidence. When summarizing or proposing changes, include source ids, titles, snippets, quotes, locations, and chunk ids when available.

Treat observations and models as learned workspace context, not source evidence. Do not cite them as proof; use the evidence records and precise source tools for factual claims. Carry contextRunId into workflow progress so retrieval and outcomes remain inspectable.

If create-only, edit, or proposal tools are available, save useful outputs only when the user asked for durable changes. After creating durable research data, connect it to the graph when relationship tools are available.

## Research Threads

- A Research Thread is a durable, Project-scoped hypothesis with supporting, challenging, and contextual evidence, alternative explanations, missing proof, next actions, confidence, and run history.
- list_research_threads and get_research_thread use knowledge:read. Creating a case file, attaching evidence, and proposing a revision require threads:write. Starting or cancelling bounded Prism model work requires threads:run.
- Add only exact excerpts from authorized Project files, documents, or artifacts. Import an external URL into the Project first, then cite the stored source; do not invent source titles or quotations.
- Use a fresh stable idempotencyKey for each intended create, evidence, proposal, or run operation, and reuse it for retries of that same operation.
- discover_project_threads may create candidate case files and evidence. run_research_thread may add evidence and update non-terminal tracking analysis. Neither can validate, reject, incorporate, apply, or dismiss a Thread or change the canonical thesis.
- Standard MCP clients do not need MCP Tasks support. Treat runId as the durable handle, respect pollAfterMs, and stop polling at completed, failed, or cancelled.

## Track Record and Long-Horizon Work

- Belief ledger: get_belief_timeline returns what the user believed and when (Thread confidence and status, claim labels, thesis fields, catalyst verdicts, decisions). get_company_thesis_snapshots returns the canonical thesis as it stood on a date. Treat both as records of judgment, never as source evidence.
- Calibration: get_track_record summarizes resolved Threads, catalysts, and decisions (hit rate, Brier score, calibration buckets, slices by inference level, source tier, and run mode). get_agent_context_pack attaches the same summary as trackRecord by default. Weigh stated confidence against it; do not present a small sample as a verdict on the user.
- As-of retrieval: pass asOf to search_library or get_agent_context_pack to search only sources that existed on or before a moment. Combine with get_belief_timeline to test whether the evidence available at the time supported a call.
- Background research: inspect get_project_research_automation first. configure_project_research_automation opts a Project into weekly and source-triggered discovery, using its existing deep-research allowance and Prism-managed Gateway models. Supply expectedVersion (0 for first setup), focus, status, and monthlyRunBudget (default 4). direct_project_research_automation requests check_now or stop_current_run; stopping also pauses future work. Only the originating MCP client may direct it. Pausing lets an executing run finish. Findings are evidence-reviewed, never human-validated. Respect pollAfterMs and nextRunAt; do not poll sleeping work continuously.
- Campaigns: create_research_thread_campaign runs an ordered plan of bounded Thread runs (deepen, verify, red_team) with a run budget, optional recurring refresh cadence, and stop conditions. Poll get_research_thread_campaign; pause, resume, cancel, or revise remainingPlan with update_research_thread_campaign. Revisions require expectedVersion and take effect at the next run boundary. A refresh run sees the previous run's summary and the evidence added since. Campaigns never validate, reject, or incorporate a Thread.
- Durable tasks: for multi-session work, create_research_task in the authorized Project, then checkpoint_research_task after each meaningful step with the plan, cursor, evidence-linked findings, tool calls used, and expectedVersion. List active tasks with list_research_tasks at the start of a session and resume with get_research_task. Close with complete_research_task and link the Research Deltas or Threads produced; conclusions still land as review-only proposals.
- Decision journal: create_decision_journal_entry only when the user explicitly states a decision (buy, add, trim, sell, hold, pass, watch). Prism captures the price at decision when available, files a review when the review date arrives, and update_decision_journal_entry records the user's stated verdict. Journaling is a record, never a trade.
- Catalyst outcomes: setting outcomeVerdict on update_calendar_event records how a dated catalyst resolved and adds it to the track record.

## Visual Artifacts

- To pull an existing artifact from Prism, start with get_prism_workspace_context and inspect library.recentArtifacts. If the artifact is not listed there, call list_library_artifacts with query or folderId, then call get_library_artifact with the artifact id to read the full saved spec/source.
- list_library_artifacts searches artifact titles and descriptions, and returns metadata, description, and artifactUrl only. get_library_artifact returns the bounded render spec/source for chart, table, metric_card, markdown, react, and html artifacts.
- If you are unsure which visualization runtime Prism expects, call get_visualization_artifact_capabilities first.
- For raw chart/table data, call prepare_chart_table_artifact with delimited_text, markdown_table, or json_rows. It returns a normalized table or chart spec, warnings, validateWith, saveWith, and insertWith. Use table output by default; request chart output only when the user asked for a chart or the chart shape is clear.
- For higher-level requests like "create an interactive dashboard from this dataset" or "turn this thesis table into a React artifact", call plan_visualization_artifact before generating code. Treat the plan as guidance, not trusted output.
- For live Yahoo-backed market visuals such as stock prices, shares outstanding, financial history, or price-to-sales over time, call list_market_data_metrics, then resolve_market_data_bindings. Save spec.liveData with refresh.mode "on_view" so Prism hydrates values server-side. React/HTML artifacts should read window.PRISM_LIVE_DATA and must not call fetch or other network APIs.
- For screenshots or rendered chart/table images, use upload_article_image and then insert_article_visual_block with useful alt and caption text. Do not pretend screenshot charts are structured data unless the user also supplies the underlying data.
- Recommended creation flow: plan_visualization_artifact, generate the final chart/table/React/HTML payload, render and inspect live artifacts in your own browser/tooling when possible, validate_visualization_artifact, then create_artifact with destination "library" or "article_draft".
- To revisit artifacts, use list_library_artifacts with sort "updated" and follow nextCursor until null. Listings include version, updatedAt, group, and typeLabel without source payloads. Read get_library_artifact before proposing an update; preserve media declarations and live-data bindings. Project viewers expose Edit and version restore, which appends history rather than deleting it.
- When saving an artifact, include a concise description when possible: 1-3 plain-language sentences explaining what it shows, the source basis, and why it matters for future search and AI retrieval.
- Before saving a complex live visualization, call validate_visualization_artifact with artifactType plus spec.
- Use create_artifact directly when saving a chart, table, metric card, note, or live visualization. It is available in Prism's compact MCP catalog; use the returned creation payload as-is rather than routing it through execute_prism_action. destination "library" requires library:write; destination "article_draft" requires drafts:write and returns a canonical tiptapNode plus a deprecated quillEmbed compatibility field.
- create_library_artifact, create_article_artifact, and create_visualization_artifact remain available for existing clients, but create_artifact is the recommended default.
- Use insert_article_visual_block when an uploaded inline image or existing artifact should land at the start, end, or a marker like [[visual:revenue-chart]] in an active article draft; pass the latest expectedUpdatedAt from get_article_draft_for_edit.
- Use attach_article_artifact_embed only when an existing artifact should be appended or prepended to an active article draft and marker placement is unnecessary; pass the latest expectedUpdatedAt from get_article_draft_for_edit.
- Runtime selection:
  - If you created HTML, call the create tool with artifactType "html" and spec { source }.
  - If you created TSX or React, call the create tool with artifactType "react" and spec { source }.
  - If you used Python in your own isolated environment to compute output, convert the result to chart, table, markdown, react, or html before saving it to Prism.
- Prefer artifactType "react" for generated TSX components with inline data, Recharts, lucide-react icons, d3, or three.
- Use artifactType "html" for portable self-contained HTML/CSS/inline JS documents, SVG process diagrams, or local click interactions.
- HTML and React artifacts must remain local-only: no external scripts, stylesheets, images, fetches, workers, storage APIs, iframes, forms, or navigation APIs. To render existing private Library images, audio, or video without embedding bytes, put each authorized file in `spec.libraryMedia` as `{ fileId, alt, caption?, sourceLabel? }` and read `window.PRISM_LIBRARY_MEDIA[fileId].url` inside the artifact. Prism injects only access-checked same-origin media URLs at render time; do not put `/api/library/files/...` directly in source. Validation errors report blocked external resource URLs when Prism can identify them.
- Prism does not execute Python source. Use Python only in your own isolated environment, then save a finished chart/table/markdown/react/html artifact.
- Prism does not render previews through MCP. If you rendered a preview with browser or vision tooling, summarize that in previewInspection when calling create_artifact.

## Article Drafts

- Use get_article_drafts for draft metadata only; pass folderId to limit results to an authorized Writing Project. Use get_article_draft_for_edit when you need the full body before revising.
- Use create_article_draft to create an article, essay, report, or newsletter. Pass an authorized Project folderId to target that Project, or omit it for the global Writing Studio. It does not publish.
- Use update_article_draft with the latest expectedUpdatedAt from get_article_draft_for_edit or create_article_draft. For AI-generated prose, submit contentText with Markdown; Prism normalizes headings, bold spans, and simple Markdown tables. Reads return canonical TipTap content. Canonical TipTap JSON, raw TipTap JSON, and legacy Quill Delta are accepted on writes.
- For articles with planned visuals, place stable markers such as [[visual:revenue-chart]] in the draft body, upload or create the visual, call insert_article_visual_block with placement { type: "replace_marker", marker }, then re-read the draft before further edits.
- Article content is returned as { format: "tiptap-json", version: 1, doc: { type: "doc", content: [...] } }. Raw TipTap documents and Prism's legacy quill-delta document shape remain accepted on writes for compatibility. For generated prose, contentText Markdown is simpler and preferred.
- Put the article title in the draft title field, not as a body # heading. In article bodies, use H2 for major sections and H3 for subsections.
- Use real rich-text bold marks for date labels, term labels, and short lead-ins instead of raw **asterisk** syntax when sending quill-delta or TipTap content.
- Supported article blocks include headings, paragraphs, lists, quotes, code, links, ticker mentions, image blocks, dividers, and artifact embeds.
- Prism normalizes common Markdown contentText syntax: ## headings become H2, ### headings become H3, simple **bold** spans become bold rich text, and body # headings are treated as H2 because the article title belongs in the title field.
- Do not rely on raw Markdown tables staying readable as plain text. For simple article tables, contentText may include Markdown pipe tables and Prism will convert them into structured table embeds.
- For durable or reusable tables and visuals, use create_artifact with destination { type: "article_draft", documentId }, then insert the returned artifactId with insert_article_visual_block.
- For raw data that should become a chart or table, call prepare_chart_table_artifact, validate the returned artifactType/spec, save it with create_artifact, then insert the returned artifactId with insert_article_visual_block.
- Use upload_article_image for generated article images. Pass imageBase64 or a base64 dataUrl, never a remote image URL.
- For hero images, set placement to "cover"; Prism updates the draft coverImageUrl immediately.
- For inline images, set placement to "inline" and insert the returned imageUrl with insert_article_visual_block.
- Use attach_article_source to connect claims, source logs, Project files, Project documents, or URLs to the article evidence trail.
- Do not call draft tools to publish, schedule, delete, send emails, or update already published posts. Those actions stay inside Prism.

## Posted Articles

- Use get_published_posts to list the user's own non-archived posted articles when a filtered metadata list is sufficient.
- Use revise_writing_object with resolve_writing_object when the user describes a post by title, ticker, Project, or subject.
- Use get_published_post_for_revision through revise_writing_object to read the complete body, stable block ids, exact citations, cover metadata, publication metadata, and revision state.
- Use fork_published_post_to_revision_draft before changing a published article. Patch only the private draft with stable block operations and exact citations. The public post remains unchanged until the user republishes it in Prism.
- get_published_posts remains available through granular discovery for filtered metadata listing. get_published_post_evidence_health remains the source, claim, stale-source, and contradiction health check.

## Relationship Mapping

- Relationship mapping is part of the default workflow. When graph:write tools are available, connect newly proposed or created data to the relevant Prism context instead of leaving it isolated.
- Use list_library_relationships first when checking existing graph edges or avoiding duplicates.
- Prefer create_library_relationships after creating private notes, thesis reviews, thesis update proposals, source-backed drafts, or artifacts when more than one edge is needed. Use create_library_relationship for a single edge.
- Use the most specific relationship that is true: supports, contradicts, references, cites, derived_from, updates, summarizes, mentions, duplicates, or related_to.
- Connect sources and outputs to the most precise available node ids, such as claims, companies, folders, drafts, published posts, thesis reviews, Project files, Project chunks, or artifacts.
- If the exact relationship is uncertain, use related_to with concise notes explaining why the connection matters.

## Project Canvas

- Project Canvas is a user-authored visual workspace inside Prism Project. It is separate from the system Knowledge Graph: canvas edges are visual unless a Prism tool explicitly saves them as graph relationships.
- Use list_library_canvases and get_library_canvas to inspect existing canvases before creating or updating visual maps.
- Canvas data is stored as JSON Canvas-compatible { nodes, edges } with Prism refs on nodes. Preserve existing node ids, positions, sizes, groups, colors, labels, and edges unless the user asks to change them.
- Use create_library_canvas to make a new workspace. Use update_library_canvas only after reading the latest canvas, and pass the latest updatedAt as expectedUpdatedAt.
- update_library_canvas replaces the full canvas JSON. Include every card and edge that should remain; do not submit partial patches. Use dryRun true to preview added, removed, and changed nodes/edges. Pass allowRemovals true only when the user intended removals.
- Do not delete or overwrite user-authored canvas cards unless explicitly asked. When adding agent-created cards, place them near the relevant context and label connections clearly.

## Safety Boundaries

- Read-first is the default. Do not mutate Prism unless the connected tool explicitly exposes a relevant create-only, edit, or proposal action.
- Durable memory is explicit and correctable. Never save hidden chain-of-thought, secrets, transient instructions, or an inferred personal preference without user intent. Correct or forget only stable memory ids inside the client's authorized folders.
- Do not publish posts, send emails, submit external forms, click Email links automatically, import arbitrary websites, edit saved thesis fields directly, perform pixel/video timeline edits, or trigger Prism-owned background research unless Prism exposes a tool for that exact action. Research Thread run tools are the only bounded model-work exception and require threads:run. YouTube transcript import is a narrow Project video source tool, not a general video/audio download tool.
- Email tools can read selected messages, trust/block senders, organize the inbox, and save edited copies into authorized Projects when scoped. They cannot mutate received originals, send email, create external accounts by themselves, revoke/regenerate addresses, permanently delete mail, or bypass user-authorized browser/signup flows.
- Writing tools are composition and private revision tools only. They cannot publish, schedule, delete, send subscriber emails, or overwrite a published post. A published post can be read in full only for a linked private revision flow, and a person must republish it in Prism.
- Treat thesis updates as proposals for user review, not as direct changes to the user's saved thesis.
- Use list_research_deltas to inspect pending, applied, or dismissed thesis-change proposals. MCP clients may create proposals, but only the user can approve or dismiss them in Prism.
- Explain Research inbox items as proposed updates: identify the triggering source when known, the exact saved claim or thesis field affected, and what applying the proposal would change. Supply source references and exact target claim IDs when the action supports them. The UI evidence path shows these recorded links; never infer a supports/contradicts relationship from an affected-claim ID, present a generated explanation as a source quotation, or describe a pending proposal as already applied.
- Research Thread revisions are proposals too. MCP exposes no apply, dismiss, validate, reject, or incorporate tool; those decisions remain human-only.
- Keep user-authored content separate from UI or tool instructions. Do not rewrite the user's voice unless asked, especially when updating existing Project text.
- Portfolio write tools mutate Prism's snapshot tracker only. Use create_portfolio, update_portfolio, delete_portfolio, add_portfolio_holding, update_portfolio_holding, and delete_portfolio_holding only when those exact tools are available and the user wants Prism tracking records changed. Position writes accept quantity plus an as-of date (or legacy openedAt fallback), optional average or total cost basis, nullable purchase date, shared positionContext, account moves, duplicate strategy, and an owned libraryFileId as provenance. They cannot place trades, connect brokerage accounts, execute transactions, or run the staged AI statement importer. Markets and Project watchlists use their own explicit tools and scopes.
- If a needed granular action is not in the default catalog, search discover_prism_actions and execute it through execute_prism_action. If a default workflow tool is authorized but missing from the host, report the capability-handshake gap and continue with the safest verified callable workflow.