MCP reference
Everything a developer or a careful user needs to know about IPGuru's MCP server: where it is, how sign-in works, what each tool does and what it costs. For step-by-step setup, see the guide for your assistant.
Addresses
All addresses use Streamable HTTP. The server is stateless, so any request can reach any instance.
| Address | Tools |
|---|---|
https://mcp.ipguru.ai/mcp | Every tool: brainstorm, structure, deliverables, studio, director, publication and projects. Use this unless your client limits the number of tools. |
https://mcp.ipguru.ai/mcp/brainstorm | Brainstorm tools only. |
https://mcp.ipguru.ai/mcp/structure | Structure tools, plus open_session. |
https://mcp.ipguru.ai/mcp/deliverables | Deliverables tools, plus open_session. |
https://mcp.ipguru.ai/mcp/studio | Studio tools, plus open_session. |
https://mcp.ipguru.ai/mcp/projects | Projects tools, plus open_session. |
https://mcp.ipguru.ai/mcp/director | Director tools, plus open_session. |
Sign-in
S256). Clients register themselves with dynamic client registration and authenticate at the token endpoint with the client secret they receive. Refresh tokens rotate; reusing an old refresh token revokes the connection.WWW-Authenticate: Bearer resource_metadata="...", pointing to the discovery document below.Authorization: Bearer ...) are for clients that cannot sign in with OAuth. Members make them in the IPGuru app under Account, Connected apps, Make an access key, with the permissions they choose and an expiry of 30, 90 or 365 days or none. The key is shown once. A key stops working when it expires, when the member removes it, or when the member's sign-in ends, for example after a password change.| Endpoint | Address |
|---|---|
| Protected resource metadata | https://mcp.ipguru.ai/.well-known/oauth-protected-resource/mcp (append the family, for example /mcp/brainstorm) |
| Authorization server metadata | https://mcp.ipguru.ai/.well-known/oauth-authorization-server |
| Issuer | https://mcp.ipguru.ai/ |
| Authorize | https://mcp.ipguru.ai/authorize |
| Token | https://mcp.ipguru.ai/token |
| Register | https://mcp.ipguru.ai/register |
| Revoke | https://mcp.ipguru.ai/revoke |
Permissions and cost
Every tool carries one scope tag. A tool that can do several things carries the highest scope any of them needs. Reads, writes and removals sit in separate tools. Every tool also carries MCP annotations: a title, readOnlyHint, destructiveHint, idempotentHint and openWorldHint. Only tools that remove something, or publish or withdraw a public page, are marked destructive.
| Scope | Consent page wording | What it covers |
|---|---|---|
| read | Read your scenarios and records | Reads, catalogues, polling jobs and runs. Free. |
| write | Change scenarios and records | Saving settings, records, cards, descriptions and selections. A stage change can also start entry work when the connection has Spend; without Spend, it still changes the stage and reports the work it skipped. |
| spend | Put the crew to work and spend your allowance | Crew turns, model and provider work, documents, searches, images and Director runs. Uses the member's allowance, the same as the same action in the app. Some spend tools also have free actions; each tool's description says which. |
A call without the scope it needs is refused with scope_required: <scope>; reconnect with the <scope> scope. The member's membership and allowance still apply to every call.
Limits
| Call duration | Every tool returns within 45 seconds. Longer work is a job, a turn or a run that the client polls. |
| Request rate | 10 requests a second per connection per address, with bursts up to 30. |
| Sign-in routes | 30 requests a minute per IP address. |
| Uploads | 15 MiB per file (Vault objects and references). Public web pages added as sources: up to 15 MB. |
| Pages | Transcript and event reads return at most 200 events per call. Lists return a cursor for the next page. |
| Activity record | Each call is recorded in the member's activity by tool name, connector version and connection. Arguments, results and credentials are not stored in that record. |
How the tools work
Call open_session first. It returns a session handle that every other tool takes, with the account summary, the first scenario cards and server defaults.
Anything that takes more than a few seconds returns an id at once. Poll it with the matching tool: wait_for_turn for a crew turn, document_run for a document, studio_run_status for an image, director_run_status for Director, and the *_job tools for other jobs. Pass wait_s (up to 45) to wait for progress. still_running means call again. A wait ending does not stop the work.
Writes that change shared records take the current revision from the last read. A stale revision is refused with a conflict. Read again and decide; do not retry blindly.
Tools that start paid work accept a caller-chosen client_request_id, idempotency_key or command_id. After a lost reply, repeat the call with the same identity and body, or look it up first with turn_request, read_preparation or the job status. You get the original work back instead of a second charge.
A finished crew turn returns the open cards: options and recommendations waiting for the member. A new message does not answer or close a card. Use card_act. review_open_items lists everything waiting on the member.
Scenario tools return an app_url that opens the same saved work in the IPGuru app.
playbook(mode) returns IPGuru's current guide for a workflow. The same guides are available as MCP prompts.
Prompts
| Prompt | Arguments | What it does |
|---|---|---|
harness | topic (optional) | Guide a brainstorm with the crew, optionally starting from a topic. |
structural | topic (optional) | Use IPGuru's method to structure the client's own thinking. |
audit | scenario_id | Audit a scenario's current signals and pick three actions. |
pack | scenario_id, action_id (optional) | Choose or start a document pack, then return its documents. |
studio | scenario_id | Prepare a scenario's Studio and review its images. |
project | project_id | Read a project's current stage and follow its FORGE workflow. |
director | scenario_id or project_id (exactly one) | Plan, follow and review a Director run for the selected scenario or project. A project run follows its current stage verdict; criterion Detach is separate, pending work wakes automatically, and Resume cannot advance a stage. |
debate | scenario_id | An expert debate. A last resort, after discussion, questions, research and critique. |
Resources
Read these with the client's resource support, or with the fetch tool.
| Resource | What it holds |
|---|---|
ipguru://scenarios | The member's scenario cards. |
ipguru://scenarios/{scenario_id} | One scenario card. |
ipguru://scenarios/{scenario_id}/transcript | The transcript with speaker names and roles. |
ipguru://scenarios/{scenario_id}/idea | The Idea record. |
ipguru://scenarios/{scenario_id}/signals | The signal matrix. |
ipguru://scenarios/{scenario_id}/record | The scenario record: decisions and suggestions. |
ipguru://scenarios/{scenario_id}/lens | The active frame, theme and coverage. |
ipguru://catalog/{kind} | One catalogue. |
ipguru://scenarios/{scenario_id}/documents/{run_id}/{kind} | A finished document: markdown, docx or pdf. |
ipguru://scenarios/{scenario_id}/references/{reference_id} | One reference. |
ipguru://scenarios/{scenario_id}/vault | The scenario Vault listing. |
ipguru://scenarios/{scenario_id}/vault/files/{file_id}/versions/{version_id} | One Vault file version. Add /thumbnail for its thumbnail. |
ipguru://scenarios/{scenario_id}/studio | The Studio record: description, art direction, shoot list, roles and runs. |
ipguru://scenarios/{scenario_id}/visual/images/{image_id} | One image. Add /thumbnail for its thumbnail. |
ipguru://projects | The member's project cards. |
ipguru://projects/{project_id} | One project, its stage and threads. |
ipguru://projects/{project_id}/documents/{run_id}/{kind} | A finished project document: markdown, docx or pdf. |
ipguru://projects/{project_id}/vault/files/{file_id}/versions/{version_id} | One project Vault file version. Add /thumbnail for its thumbnail. |
Files too large to return open in the app instead: the project's or scenario's Documents, Studio or Vault.
Tools
The descriptions below are the ones the server gives your assistant.
Sessions, scenarios, crew turns, cards, follow-ups, the crew, comparisons and debate.
| Tool | Scope | What it does |
|---|---|---|
open_session | read | Call first. Verifies the signed-in token and returns the session handle every other tool takes, the account summary, the scenario cards and the server defaults. Free. |
search | read | Find scenario, library and reference records by words in their titles, questions, topics, notes or source URLs. This is a projection over the three lists, not a server search index; every query word must match. Needs open_session; references additionally need scenario_id. Free. Results include an exact id for fetch and the app's Brainstorm entry URL; the app does not yet route individual result IDs. |
fetch | read | Read a resource by its ipguru URI, or the full record for an id from search: scenario:<id>, library:<id> or reference:<scenario_id>/<id>. Needs open_session. Free; a scenario includes its transcript page and next_after cursor, and a reference includes its content. |
focus | read | List focused references after open_session and selecting a scenario. Free. |
add_focus | write | Add a focused reference with scope keep or once. Needs open_session, a scenario and reference_id from list_references. Free. |
clear_focus | write | Clear focused references after open_session and selecting a scenario. Pass reference_id to clear one reference; omit it to clear all focus. Free. |
participant_act | spend | Mute or unmute an agent, set in_character or out_of_character, or run_action using an action_id from catalog(quick_actions). Needs open_session, a scenario and the card's revision for mode changes. Mode changes are free; run_action runs a model. |
extract_roles | spend | Extract useful roles from the scenario after a conversation establishes the idea. Needs open_session and a scenario. Runs a model and is metered. A degraded result includes error_code explaining why no roles were extracted. |
set_response_profile | write | Set the scenario's response format, length, tone, preset or custom instructions. Needs open_session and the card's revision; omitted options remain unchanged. Free. |
set_crew_participation | write | Enable or disable a seated crew participant after read_consultation identifies them. Needs open_session, the scenario, participant_id and the card's revision. Free. |
read_roster | read | Read available participants and their roles after selecting a scenario. Needs open_session. Free; use returned identities for participant actions. |
read_crew_expert | read | Read the generated overview of an expert currently seated in the scenario. Needs open_session and profile_id from read_consultation. Free; an unseated profile is refused. |
feature_guide | read | Read the feature guide after open_session and selecting a scenario. Free. |
feature_guide_act | write | Record a feature-guide episode with claim, shown, visited or dismissed. Needs open_session and a scenario; claim needs episode_id, other actions need feature or episode_id from feature_guide. Free. |
list_scenarios | read | Read saved scenario cards, Idea-completeness scores with freshness, publication status and app links. Free; never runs a model. Needs open_session. Follow next_cursor for more; limit is 1 to 100. status is all (default; archived scenarios are marked), active or archived. A score is not patentability or Director completion. |
start_scenario | spend | Create a scenario from a centre topic after open_session. mode brainstorm opens a conversation; mode expand also queues and returns its initial expansion job. Creation queues background model-backed Topic Map work even with generate_title false; optional title generation and expansion may add metered work. preparation=wizard commissions the UI's durable Idea/roles/crew/greeting/source setup for brainstorm mode; use read_preparation. Default none retains raw creation. Retain client_request_id BEFORE sending, then reuse it after a lost response to avoid duplicate scenarios/spend. chat_mode is nova, synthesised or roundtable; send_message then wait_for_turn runs a conversation turn. |
read_preparation | read | Read durable wizard preparation progress after start_scenario. Free; a queued job is not completion. Work continues after disconnect. |
prepare_scenario | spend | Commission shared wizard conversation preparation for an existing scenario, or return its existing job. May spend on Idea/crew/sources; needs current scenario revision. Inspect with read_preparation. |
retry_preparation | spend | Resume unfinished conversation preparation using its current scenario revision. Keeps completed stages. An uncertain interrupted stage requires explicit retry_uncertain after review and may spend again. |
contrib_summary | spend | Summarise selected crew contributions after read_events or read_scenario gives their event indexes. Pass event_indexes and the optional synthesis_index exactly, including zero. Needs open_session and the owned scenario. Uses the API's lazy contributor analysis; analysing nonempty contributions calls a metered model. Returns its actual summary. |
turn_request | read | Look up the turn for client_request_id retained from send_message or queue_followup after an ambiguous disconnect. Needs open_session and the same scenario. Free; returns acceptance, saved/completed flags and the turn when it exists. A queued input has no turn until run-next starts it, so accepted false does not prove the input was lost. Check list_followups before resending and reuse the same key. |
validate_scenario | read | Read the existing scenario's project, knowledge, memory and storage readiness after open_session, before investigating an unavailable feature. Free diagnostics, with no repair or infrastructure change. The existing read_validation tool remains available. |
debate_motions | read | Advanced, last-resort expert debate: use only after crew discussion, questions, research and critique have failed to resolve the issue. Read suggested motions. Call open_session first, then read_roster to choose the debaters. Free. |
compare_scenarios | spend | Compare two to four owned scenarios after open_session and list_scenarios. persist false returns only their transient scope bundle, without a model analysis or merge. persist true creates a deterministic, tier-metered comparison with frozen inputs and a proposal. Keep its comparison_id and idempotency_key, then read and review it with comparison before any apply. Sources are not changed. |
comparison | read | Read a persisted comparison after open_session and compare_scenarios(persist true). Free; reading does not run a model. |
apply_comparison | write | Apply only a persisted comparison's reviewed accepted_proposal to a separate owned target_scenario_id after open_session and comparison. The target must not be one of the sources. Stores the accepted proposal in the target's compare-merge history and advances its revision; it does not rewrite the consolidated Idea fields. Omitted accepted_proposal uses the saved proposal. Deterministic and free, with no model call. Keep the returned idempotency_key for the same apply retry. |
debate | read | List or read saved expert debates after open_session and selecting a scenario. Read needs debate_id from the list or debate_act(create). Free; use debate_status to wait for a revision or status change. |
debate_act | spend | Advanced, last-resort expert debate. Commission only after ordinary crew discussion, questions, research and critique have failed; never for routine coverage. Create after open_session, debate_motions and read_roster, passing the scenario_revision and chosen profiles. Create records the motion and cast; it does not generate a turn. Advance queues metered model work; autoplay commissions a bounded sequence. Keep its job_id for generation_job and use debate_status to read the debate itself. Control, cast, interject, next_motion and dispose only edit the record. Every edit after create needs the debate's current revision. Interject records your point for a later advance; dispose sends a reviewed disposition to the scenario as send_suggestion or leaves it open. Control accepts pause, resume, pace, steer, end or next_motion. Keep the returned idempotency_key for create and advance retries. Paused or active describes the debate, not its job. |
debate_status | read | Read a debate after create or advance. With wait_s, poll for at most 45 seconds and report its actual status, phase and turn count. Pass after_revision from the preceding read to return as soon as a newer step is saved. Otherwise wait for a revision change or a status outside active/queued/running. active can mean waiting for your next advance, so it does not prove a worker is running; use generation_job with advance's job_id for worker failure or completion. wait_exhausted preserves the actual debate status. Free after open_session. |
read_scenario | read | The scenario card, its participants, chat mode and the transcript projected to speaker names and roles, from transcript_after onwards (at most 200 events; loop on next_after; the default -1 includes the first event at index zero), with each message's cards and open_card_count; review_open_items lists the open ones. Free. |
update_scenario | write | Rename or re-centre a scenario, or change its question presets. Needs the card's current revision; a stale revision answers a conflict. Free. |
send_message | spend | Send the user's message to the crew. Set the chat mode first with set_chat_mode: nova gives one voice, synthesised gives expert replies then Nova's summary, and roundtable gives every voice. Message wording does not select who answers. Queues it as a follow-up and hands the turn to the worker; returns the queue state and the active turn. When a turn is already running the item stays queued and the worker runs it after that turn; the response names the active turn. Then call wait_for_turn with the turn_id. Costs a model turn. Returns client_request_id for turn_request lookup; supply and retain your own key before sending if a lost reply must be recoverable. Reuse that key for the same input: replay returns its recorded state without running another queued turn. If it never started, inspect list_followups before explicitly choosing followup_act(run_next). |
wait_for_turn | read | Wait for a turn to finish, at most timeout_s seconds (capped at 45), then return the new transcript events since after_event (default -1 includes index zero) with speaker names and roles. status still_running means call again with the returned next_after; it is not an error. Reports the crew's activity and new contributors while waiting. Once the turn has finished it also returns open_cards and open_card_count: a card stays open until card_act answers or closes it. On completion next_turn_id names a queued turn that has started; wait for it too. Free; loop until status is completed, failed, stopped or cancelled. |
read_events | read | The raw event page after the requested index, at most 200 per call. The default -1 includes index zero. Free; prefer read_scenario for a transcript with speaker names. |
review_open_items | read | Everything waiting on the member: the open cards (options and recommendations the crew raised that read Needs review in the app), the pending suggestions in the scenario record and the latest Director run's open questions. Each row names what closes it: card_act, suggestion_act (dismiss, park or adopt) or director_control(answer). Call it before handing back to the member. Free. |
card_act | spend | Answer or close one card by proposal_id, with the actions the app offers. accept (a recommendation), choose (option_id or option_text) and choose_many (selections of {option_id, priority primary or secondary}) record the answer. A card from the latest exchange starts a metered reply from its raiser alone: Nova for her own card, or the expert who raised it; Nova stands in if that expert is muted or unseated. An older card records the answer without a reply. record (destination ruled_out, parking, actions, suggestions or decisions), ignore, undo and reopen are free and run no model. follow_up means ask about the card using send_message; it neither answers nor closes it. Without action, ask the member through elicitation. Never answer or close cards without the member's decision. Returns the API result. Wait for a started reply with reply_turn_id; if the reply is waiting, resolve reply_request_id through turn_request before waiting. nova_followup_status none on an older card means no reply will run. |
stop_turn | write | Stop a running turn. Replies already in progress may still land after Stop. Returns the queue state. Free. |
list_followups | read | The follow-up queue: queued items, the active turn and capacity. Free. |
queue_followup | write | Queue a follow-up without starting it (behavior queue), or steer the running turn (behavior steer). Steer requires an active turn; otherwise steer_no_active_turn is returned and nothing is queued. A queued item starts automatically after the current turn finishes. Free to queue; the later turn is metered. send_message is queue plus run-next. Returns client_request_id; retain or supply it for the same input's retry. Before resending after a lost reply, inspect list_followups and turn_request. |
followup_act | spend | Act on the follow-up queue: edit (item_id, text), reorder (item_id, position), promote an item to a steer (item_id), run_next, or resume a failed saved turn. Stop does not cancel replies already in progress; they may still appear. run_next and resume can start a model turn and are metered. |
remove_followup | write | Remove a follow-up from the queue after open_session and selecting a scenario. Needs item_id from list_followups. Free. |
set_chat_mode | write | Set how the crew answers: nova (one voice), synthesised (experts, Nova sums up) or roundtable (every voice). Needs the card's revision. Free. |
apply_theme | spend | Apply a theme pack by key (see the structure server's catalog theme_packs), or clear it with no key. Needs the card's revision. Changing the theme re-ranks the recommended experts with a model call. |
apply_frame | write | Apply a thinking frame by key (catalog frames), or clear it with no key. Needs the card's revision. Free. |
recommend_experts | spend | Ask for a recommended roster of experts for the scenario; alternate asks for a different set, force re-runs it. Runs a model: costs a model call. With force or alternate, the recommendation may replace the seated crew if the member has not edited it; read_roster afterwards. Use set_experts to choose a roster yourself. |
set_experts | write | Seat the experts by profile id (from recommend_experts). Needs the card's revision. Omit profile_ids to choose from the saved recommendation. This asks before acting where the client can ask. Clients without choices need explicit profile_ids. Free. |
greet | spend | Ask Nova to open the conversation. The greeting is an appended event, not a turn: this call returns it as events with speaker names. If the card's recommendation_state is pending the crew is still being seated and the greeting names no experts; call read_scenario until it is ready first. Calling greet again returns the existing greeting (already true). The greeting is deterministic and free, with no model call. A conversation with messages but no greeting is left as it is. |
duplicate_scenario | write | Copy a scenario's settings into a new one (never its transcript). Free. |
delete_scenario | write | Delete a scenario. Pass the card's revision while it is live; deleting again is idempotent. The scenario leaves every list at once and is erased in the background: read_scenario reports status deleting until then, 404 once it is gone, or delete_failed if the erasure could not finish. This asks before acting where the client can ask. Free. |
The Idea record, signals, the expander, the pivot, questions, verification and the catalogues.
| Tool | Scope | What it does |
|---|---|---|
apply_expansion | write | Apply the kept expansion items after read_expansion and mark_expansion. Needs open_session, a scenario and the returned expansion_revision. Free. |
recollect_expansion | write | Recollect the expansion against the current scenario after read_expansion. Needs open_session, a scenario and expansion_revision. Free; read the returned revision before editing. |
register_act | write | Act on the Idea's assumptions, tests or open_gaps after read_idea. Actions are add, correct, settle, withdraw, record_result, not_running and resolve; the API checks which actions fit each lane. Needs open_session and the card's revision. Pass item_id for an existing entry. Free. |
delete_register_entry | write | Delete an entry from the Idea's assumptions, tests or open_gaps after open_session and read_idea. Needs lane, item_id and the card's revision. The API checks which lanes permit deletion. Free. |
restore_idea | write | Restore a saved Idea revision after checking the current Idea and scenario card. Needs open_session, target_revision, expected_idea_revision and the card's revision. Free. |
question | write | Create or edit a custom question after open_session and catalog(questions). Create needs question_text; edit needs question_id and the question's revision. Free. |
delete_question | write | Delete a custom question after open_session and catalog(questions). Needs question_id; optional question_text names the confirmation. Removes the question and asks before acting where the client can ask. Free. |
read_validation | read | Check the selected scenario's project, knowledge, memory and storage readiness before investigating an unavailable feature. Needs open_session and a scenario. Free; returns the API's diagnostic results without changing infrastructure. |
start_verification | spend | Start a verification method after catalog(verification_methods), read_signals or read_idea. Needs open_session, a scenario, method_key and idea_revision; optionally bind a risk_signal_key, assumption_id or consultation_id. Runs a model and is metered; poll the returned run_id with verification_run. |
verification_run | read | Poll the run_id returned by start_verification. Needs open_session and the same scenario. Free; the returned result records its evidence and outcome. |
question_scan | read | Read the structural question scan after open_session and selecting a scenario. Free. Use question_scan_act to start a scan or dismiss a question. |
question_scan_act | spend | Start a structural question scan or dismiss a question by question_id from question_scan. Needs open_session and a scenario. Dismissing is free; start runs a model and returns a generation_job handle. Read question_scan again when done. |
generation_job | read | Poll a job from question_scan_act or list generation jobs when job_id is omitted. Needs open_session and the same scenario. after continues job events; action and target_id filter the list. wait_s waits up to 45 seconds with progress for one job. Free; read the generated surface after completion. |
playbook | read | The structured-brainstorm walk as text: mode harness (Claude drives the crew for a person), structural (the caller thinks and IPGuru scaffolds), pack, audit, studio, director, debate or forge (project stages). Free; read it before starting that workflow. The same guidance is available as prompts. |
catalog | read | One of IPGuru's catalogues, unchanged from the route: starters, questions, intents (with the intent JSON schema), signals, dimensions (the eight axes A to H, from the signal catalogue), frames, methods, verification_methods, theme_packs, design_criteria, quick_actions, source_kinds (reference classifications) and invention_profiles (the subjects, claim forms and special handling an invention profile is made of). Needs open_session. Free. |
set_intent | write | Set the strategic intent stack (entries from catalog intents) and re-weight the dimensions. Needs the card's revision. Free. |
set_invention_profile | write | Confirm or change what the invention is: one subject and one or more claim_forms, keys from catalog(invention_profiles). Studio makes nothing for a scenario until this is confirmed. It is the person's decision: ask them, and never confirm a guess. Changing a confirmed profile keeps earlier Studio work, labels it as made for the old profile and returns how many outputs that was. Pass exactly one of scenario_id or project_id and the current profile revision, 0 for an unconfirmed project. Free. |
read_idea | read | The Idea record: overview, fields, decisions, will-nots, assumptions, next tests, actions, remaining gaps and the parking lot. Free. |
refresh_idea | spend | Ask Nova to re-consolidate the Idea from the transcript (focus all or summary). Runs a model: metered. Returns the Idea view. |
score_idea | write | Persist the current deterministic Idea-completeness rubric and dimensions. No model call; free. Does not assess patentability or prove Director completion. |
read_signals | read | Read the signal audit after audit_signals, or check whether an audit is available. Optionally select one dimension by its A to H letter or catalogue key; all other audit metadata is retained. Needs open_session and a scenario. Free. |
frame_coverage | read | List frames and coverage states or read a frame's slots after open_session and selecting a scenario. Read needs frame_id from the list. Free; evaluate_frame_coverage runs a new evaluation. |
evaluate_frame_coverage | spend | Evaluate coverage for a frame_id from frame_coverage after open_session and selecting a scenario. Runs a metered model; read frame_coverage afterwards for the result. Accepts an optional manifest_version. |
read_connections | read | Read the connections of a knowledge-map record after selecting its record_type and record_id. Needs open_session and a scenario. Pass the returned cursor for the next page; limit is optional. Free. |
read_lens | read | Read the active frame, theme and frame coverage together after selecting a scenario. Needs open_session. Free; coverage_available is false when the knowledge map is disabled. |
audit_signals | spend | Start a signal audit against the Idea at idea_revision (from read_idea or read_signals). A job: returns the job id; poll with signals_job. |
signals_job | read | Poll a signal audit job by id after open_session. wait_s waits up to 45 seconds with progress. Free. |
signal_act | spend | Act on one signal: dismiss or restore it (free), or suggest from it (runs a model; suggest_action names what to suggest). Needs the card's revision. |
read_evaluation | read | The Idea evaluation. Free. |
read_expansion | read | The expansion state and its expansion_revision, which every expander write needs. Free. |
generate_expansion | spend | Ask the expander for items: seed text, depth same, deeper or wider, an optional section_key, focus_item_id, recentre_direction_id or method_key. Runs a model and takes tens of seconds: a job; returns the job id, poll with expansion_job. Needs expansion_revision from read_expansion. |
expansion_job | read | Poll an expansion job by id. The items arrive on the expansion state when it is done. wait_s waits up to 45 seconds with progress. Free. |
cancel_expansion_job | write | Cancel an expansion job by id after open_session and selecting a scenario. Stops work and retains the job record. Free. |
mark_expansion | write | Record the caller's judgements on the expansion: locked, declined and restored item ids, adjacent direction ids, authored items and which sections are open. Free, and it must precede commit_expansion. Needs expansion_revision. |
undo_expansion | write | Undo the last expansion mark. Free. Needs expansion_revision. |
commit_expansion | spend | Commit the marked expansion into a scenario: title, summary, frame_key (catalog frames), optional theme_key; preview true returns the committed shape without committing. Runs a model: metered. Needs expansion_revision. |
pivot | spend | Move the idea: action start (optional seed) opens a pivot and returns its pivot_id; advance (pivot_id, answers, direction forward or back) moves through it; commit (pivot_id, optional title, frame_key, theme_key) commits; cancel (pivot_id) drops it. start, advance and commit run a model: metered. Needs the card's revision. |
read_record | read | The scenario record: decision rows and the Idea's register. Free. |
record_act | write | Act on record rows in bulk: reverse, park, complete, activate, adopt or dismiss the items (each an object naming the row, as read_record returns them). Needs the card's revision. Free. |
suggestion_act | write | Act on one suggestion in the scenario record by id: discuss, adopt, park, debate, dismiss, reopen, accept or edit (with text). Needs the card's revision. Free. |
lens_helpers | spend | Run a lens helper (lens_kind frame or theme, helper name, target_key) against the Idea at idea_revision. Runs a model and is metered. A job: returns the job id; poll with lens_helpers_job. |
lens_helpers_job | read | Poll a lens helper job by id after open_session. wait_s waits up to 45 seconds with progress. Free. |
Projects, stages, records, assessments, documents, chat, collections and saved work views. The admin-only /system/patent-search-deferral setting is managed in Admin and is not available as an MCP tool.
| Tool | Scope | What it does |
|---|---|---|
list_projects | read | List your project cards. Use cursor and limit (1 to 100) for more. Needs a session. |
read_project | read | Read one project's state, server stage verdict, threads and FORGE locks. Returns access (owner, view, view_copy or edit) and read_only. A sharing invitation must be accepted in the app first. Edit access permits supported content changes; AI work uses the initiator's allowance. Manage sharing in the app. Needs a project id and session. Use read_stage for gate detail. |
read_stage | read | Read the server's current gate verdict, stage history, Observe entry work and scorecard. The verdict includes outcome, policy id/version and deferred_checks. Only Observe novelty and patent_feasibility, and Grade prior_art_search and claim_novelty, can be deferred; deferred rows are advisory and include reason and expiry. Criteria may include any_of and form, and return_advice is advice only. Stage history includes gate-entry by, run_id and trigger. Pass the returned stage_entry_id to gate_act. |
project_context | read | Read editable context fields, response profile and attribute version for a project. Use project_context_save to change them. |
ip_plan | read | Read the project IP plan, outcome, filing profiles, operating_jurisdictions and attribute version. Operating jurisdictions define the markets used by freedom_to_operate; filing profiles select examination reviews. Use ip_plan_save to change the plan. |
read_project_crew | read | Read the project crew, country personas and Sean's composition state. Needs a session and conversation id. Use recompose_sean to request a new composition. |
invention_record | read | Read the canonical invention record and completeness scorecard; editable_metadata is returned outside content. Optionally include the latest 50 revisions. Use invention_record_save for component add, edit or delete and other record edits; use invention_components for renumbering or renaming, merge_invention_components to merge and remove a component, or invention_proposal_act to accept or reject proposals. |
project_disclosure | read | Read a project's Disclosure overview and scorecards; optionally pass section_key for one section's state and currentness. Use project_disclosure_act to generate a section, generate all, keep a section current, rescore or render the application draft. |
project_drawings | read | Read project figure sources, drawing state and checks, including currentness, held drafts, held_plans, current jobs and failures, drafting_lock, saved settings, descriptions and sheet_rules. Line-drawing figures expose base_asset_id, base_asset_revision, callouts and component_ids; their line_drawing summary includes base and reference URLs, text_warning, missing_component_ids and lettering_font_px. Pass optional reference_id to read an accepted Studio image inline (up to 8 MiB). Its read route is GET /api/v1/chat/projects/{pid}/drawings/references/{reference_id}/raw; references are never filing assets. Use project_drawings_act to draft, render, apply a held draft, reorder figures or save settings; use project_jobs to follow queued work. |
project_claims | read | Read the ordered claim set, update state, waiting changes, office variants, saved checks and examination findings. Pass optional profile_id to read effective claims for one filing profile. Missing readings are not_assessed. |
assessments | read | Read assessment versions, currentness and queued work. Grade checks: freedom_to_operate, claim_novelty, design_similarity and examination, available only in Grade or Execute. disclosure_risk starts in Observe or later. An out-of-stage request returns 409. For examination, pass profile_id to read one filing profile's result; profile_id on another kind does not select a profile. Give kind for one scorecard and version for its history; claim reports are version-bound assessment_document runs. |
project_documents | read | Read actions, deliverables, runs and the artifact tree. Project scope includes 17 goal documents grouped as goal. Their stage placement uses the project upgrade capability; each pack's membership level and per-pack switch still apply. The listing exposes matches_goal, recommended and requirements answered from project sources, with document.gates in FORGE order and gate_label for required or advisory stage documents. A newer running, failed or cancelled attempt leaves the latest ready_to_review run available to open and shows the newer attempt separately. Run detail omits full project_inputs from steps. Give run_id for one saved run and kind for artifact content; opening saved work starts no generation. |
project_wait_for_turn | read | Wait up to 45 seconds for a project turn, returning new events. still_running means poll again with next_after. Needs conversation and turn ids. |
project_followups | read | Read a project conversation's follow-up queue and active turn. Needs a conversation id. |
project_read_events | read | Read up to 200 conversation events after an index. Default -1 includes index zero; use next_after for the next page. |
project_jobs | read | Read the project's work dashboard and current job states. |
project_record | read | Read the project record, decisions, parking, commitments, review board, conflicts and suggestions. |
collections | read | Read collection ids, names, order and rules for your projects. |
list_work | read | List saved scenarios and projects by recent activity. Filter by kind or collection id, and by status: all (default), active or archived. Use the returned app links to open work. |
create_project | spend | Create a project after open_session, directly from the member's fields or from project_draft's source_brainstorm_scenario_id and source_brainstorm_import_id. The API applies the account's and the project's gates. For an import, retain the returned idempotency_key and reuse it to recover the first project. Direct creation has no replay protection: check list_projects after a lost reply before retrying. Optional setup queues patent import and a Baseline pass; start_profile preserves a typed name up to 120 characters. Optional setup queues patent import and a Baseline pass; start_profile preserves a typed name up to 120 characters. Set filing countries afterwards with ip_plan_save; read_project next. |
recompose_sean | spend | Request Sean's composition for a writable project, or join its queued composition. Needs a session and conversation id. Read progress with read_project_crew. |
gate_act | write | Advance or return a project stage only when the member has asked in this conversation. Needs expected_stage_entry_id from read_stage; return also needs to_stage and a rationale. The tool asks the member to confirm. A client that cannot ask receives a link and makes no transition; declining confirmation returns changed=false. A confirmed change returns the API transition result and authoritative verdict. Advance from Execute completes the project and stops queued work. The API applies the account's and the project's gates. A call without spend changes the stage and reports entry work it did not start as skipped_work. Read read_stage after a change. |
project_pivot | spend | Act on a project PIVOT. Start with reason; cancel with expected_stage_entry_id and resume_paused=true; commit with new_direction, expected_stage_entry_id, carry and optional name. Start pauses queued work and reports work already running; cancel can resume work paused by this PIVOT. Retain the start receipt and use its stage entry id. Routes: POST /api/v1/chat/projects/{pid}/pivot/start, /api/v1/chat/projects/{pid}/pivot/cancel and /api/v1/chat/projects/{pid}/pivot. Prepared commit choices are immutable; retry with the same choices and follow the returned receipt to resume or retrieve the same successor. Completion retains the source as archived and read-only and transfers its project upgrade to the successor. MCP title: Act on a project pivot. readOnlyHint, destructiveHint, idempotentHint and openWorldHint are all false. |
project_context_save | write | Save context fields or a response_profile using expected_version from project_context. Actions: context, response_profile. Pass the selected fields as values. The API applies the account's and the project's gates. Relay any skipped_work and read project_context before another edit. |
ip_plan_save | write | Save the project's IP plan, outcome, filing profiles and operating_jurisdictions using expected_version from ip_plan. Outcome accepts patent, trade_secret, open_publication, licensing, product, funding, learning or undecided and must agree with the protection choice. Changing it records a linked Project Register decision. Saving re-resolves the seated patent team without a model call. Read ip_plan before another edit; a stale version is refused. |
assessment_run | spend | Start quick_check in Focus, refresh_search in Observe or recheck from Refine onward. Grade check kinds start only in Grade or Execute; disclosure_risk starts in Observe or later. An out-of-stage request returns 409. freedom_to_operate uses operating_jurisdictions; claim_novelty compares claims with the sealed corpus; design_similarity and examination use saved evidence. For an examination refresh or recheck, pass profile_id; another kind with profile_id is refused. For refresh_search with kind=market only, optional region is a supported two-letter country code or any; use a new idempotency_key when changing region. A market recheck uses its pinned product search and region without searching again. Reuse idempotency_key after a lost reply. Poll assessments or project_jobs and relay skipped_work. |
assessment_act | write | Accept a current version, register a recommendation, add a ready source to the sealed corpus, or record an examination finding disposition. For disposition pass action=disposition, kind=examination, finding_id, profile_id, version, disposition (address, defer or disagree), reason and idempotency_key. Route: POST /api/v1/chat/projects/{pid}/assessments/examination/findings/{finding_id}/disposition. Read assessments or project_claims for the result. The former project reference-impact-analysis GET and POST are retired; use claim_novelty. |
invention_record_save | write | Save invention record content using expected_revision from invention_record. Component add, edit and delete are validated on changed writes: numerals and case-insensitive names must be unique, and a component used by a figure cannot be deleted. A new entity or a status change to evidenced needs support: a calculation, simulation or test link/anchor, or a source anchor identifying a ready source in the same project or finished project research. Existing evidenced history remains readable unchanged. Figure tokens must name a registered component; an unknown token is refused with its line number (422). The API applies the account's and the project's gates and refuses stale revisions. A save can also queue claim checks; relay skipped_work if they do not start. Read invention_record before another edit. |
invention_components | write | Rename or renumber components using expected_revision and the current record content read from invention_record; the tool does not fetch the record itself. Actions are rename (component_id, name) and renumber (from_number, to_number; scheme="by_figure"; or scheme="order" with ordered component ids, start and step). Renumbering updates figures and matching description and claim references in one record revision. The API refuses component conflicts with 422 and stale revisions. Read invention_record for the returned revision before another edit. |
merge_invention_components | write | Use action=merge_components (the default) with source_id, into_id and expected_revision to merge components; action=remove_claim with source_id (claim id), expected_revision and optional with_dependents to remove a claim; or action=apply_claim_removal with job_id, suggestion_id and expected_revision to apply a Remy removal suggestion. Ask the member before either removal. Claim dependants are rewired to the removed claim's parents; removing an independent claim with dependants needs with_dependents=true. Read invention_record or project_claims after the change. |
invention_proposal_act | write | Accept or reject current proposed entities in one record revision. Use expected_revision and entity ids from invention_record. Supply reasons by entity id and retain idempotency_key to replay the original revision. Rejected entities remain in history. The proposal decision can also queue claim checks; relay skipped_work if they do not start. Read invention_record before another edit. |
project_drawings_act | spend | Write or render project figures. Actions: draft (figure_type, instruction, idempotency_key; optional figure_id and mode=new, change, retype, line_drawing or plan). Plan omits figure_id and figure_type, and holds up to 12 suggested figures with reasons, component_ids, new_components and optional studio_media_id without changing the record. Save chosen proposed parts once with invention_record_save, then draft chosen items in sequence with plan_job_id, plan_item_index and a stable idempotency_key per item. A held plan projects each item’s draft_job for resuming after reconnect. Drafting starts in Refine; Claims settings save in any writable phase. A line_drawing draft takes reference_media_id (an accepted Studio image candidate_id), view and component_ids. Render takes figure_id, figure_revision, render_input_digest and idempotency_key. Omit svg and the server draws a Mermaid figure or composes a line drawing; svg and png_base64 remain accepted. apply_draft takes job_id, expected_revision and as_new; reorder takes expected_revision and order containing every figure id once; settings takes expected_version, direction and label_style. Change and retype drafts remain held until applied. Read project_drawings for figures, base art, callouts, reference previews, settings and held drafts; poll project_jobs for queued work. |
project_claims_act | spend | Actions: draft (mode=write or suggest, optional focus), renumber (expected_revision, order), approve (expected_revision), undo_update (job_id, expected_revision), apply_suggestion (job_id, suggestion_id, expected_revision, operation_kind=edit, add or variant), settings (expected_version, mode and/or steer). Drafts update the complete ordered set and retain claim ids; a done job with the same key is returned as-is. Remy-written claims can change, while member-worded claims stay as written and receive suggestions. Removal suggestions must use merge_invention_components(action=apply_claim_removal), preserving the existing destructive boundary. Poll project_jobs; read project_claims for saved state. No tool was added; this is the brief 1036 fallback for removal. |
project_disclosure_act | spend | Pass project_id. Actions: generate, generate_all, keep, rescore, render. Generate needs section_key and accepts optional focus; generate_all needs no section key; keep needs expected_revision from project_disclosure; rescore accepts an optional idempotency_key; render accepts optional profile_id and run_id. Generation returns the existing job for the same key. Rescore reuses a ready full result or joins/promotes queued work. Keep returns the current revision without adding a revision when its basis is already kept. By default, render builds the main `application_draft` plus `office_renders` for selected profiles with variants. With profile_id it renders that office's application draft. Both use effective accepted claims and accepted figures with saved assets and the relevant profile's description headings. Render makes no model call, and replay for the same canonical basis returns the existing run, artifact and media. Read project_disclosure for saved section state and project_documents for the application run and artifact; project_jobs tracks queued generation and scorecard work. |
project_document_act | spend | Actions: run, accept, request_revision, cancel, export, accept_legacy, request_revision_legacy, gate_report. Use identifiers from project_documents. The 17 goal documents also run in project scope at their stage placement, subject to project upgrade stage capability, each pack's membership level and its per-pack switch. Check the listing's matches_goal, recommended, requirements, enabled and reason before running; required preconditions are resolved from project sources. Use run only when asked to generate a document; to open saved work, read project_documents by run_id. Run repeated with the same idempotency_key returns the first run; keep the generated key. Repeating request_revision, request_revision_legacy or gate_report commissions new work each time. The API applies the account's and the project's gates. Poll project_documents or project_jobs; generated work does not pass a gate. |
project_send_message | spend | Queue a message on conversation_id from read_project and start the next turn when idle. Reuse client_request_id on retries; replay does not start a second turn. Busy work stays queued. The API applies the account's and the project's gates. Follow with project_wait_for_turn or project_followups. |
project_followup_act | spend | Actions: queue, edit, reorder, promote, run_next. Read project_followups for item_id and revisions; pass the route's fields in values. Queue needs text and client_request_id, reorder needs position. The API applies the account's and the project's gates and may refuse steering. Remove with remove_project_followup. Poll project_followups or project_wait_for_turn. |
project_stop_turn | write | Stop turn_id from project_wait_for_turn in the selected conversation. Keeps its records. Read project_followups next. |
project_job_act | spend | Retry or cancel job_id from project_jobs. Actions: retry, cancel. The API applies the account's and the project's gates and permits changes only in the job's current state. Most retries requeue the same job. Retrying an assessment job creates a new phase job and leaves the old attempt terminal; poll the returned job.id with project_jobs. |
project_record_act | write | Actions: decision, promote_decision, parking, commitment, edit_commitment, extract, edit, approve, archive, convert, resurface, reverse, review_mark, resolve_conflict. Use identifiers from project_record and the route's fields in values. For a gate-linked decision, pass decision_key, gate_criterion, stage_entry_id, value, rationale and expected_version in values; take the criterion and stage entry from read_stage and the current record version from project_record. The API applies the account's and the project's gates. Archive and reverse keep the record; remove parking with remove_project_parking_item. If confirmation is stale, reread read_stage and project_record, then reuse the saved decision_key, gate_criterion, text, value and rationale with the current stage_entry_id and expected_version. The server appends or supersedes the saved decision as appropriate. Read project_record after a successful change. |
collection_save | write | Actions: create, update, reorder, move. Read collections for ids. Pass fields in values: name and optional rules for create/update, collection_ids for reorder, project_ids and collection_id for move. Scenario moves use their brainstorm_project_id. Supply project_id for a single-project move. Remove with remove_collection; read collections or list_work after the change. |
remove_project_followup | write | Remove item_id from project_followups in the selected conversation. Read project_followups afterwards. |
remove_project_parking_item | write | Remove item_id from project_record's parking list, asking first when the client can ask. Read project_record afterwards. |
remove_collection | write | Remove collection_id from collections, asking first when the client can ask. The API moves its members to the default collection. Read collections afterwards. |
project_details | read | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. attributes: /attributes; query: none; required query: none. design_guide: /design-guide; query: none; required query: none. prefs: /prefs; query: none; required query: none. tags: /tags; query: none; required query: none. |
project_expansion | read | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. This tool has one operation and takes no action argument. expansion: /expansion; query: none; required query: none. |
project_readiness | read | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. reconciliation: /workflow/reconciliation; query: none; required query: none. reconciliation_preview: /workflow/reconciliation/{preview_id}; query: none; required query: none. |
project_binder | read | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. binder: /workflow/binder; query: format, optional_ids; required query: none. binder_sources: /workflow/binder/sources; query: none; required query: none. The Binder accepts the current accepted Drawings-page figures used by Build the application. Its CORE-03 inventory includes figure revisions and image hashes; existing technical-diagram renders, trusted imports and current figures-not-applicable decisions remain supported. |
project_research | read | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. research_capabilities: /research/capabilities; query: none; required query: none. research_runs: /research/runs; query: none; required query: none. prior_art_watches: /studio/prior-art/watches; query: none; required query: none. watched: /watched; query: none; required query: none. |
project_memories | read | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. This tool has one operation and takes no action argument. memories: /memories; query: status; required query: none. |
project_crew_history | read | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. expert_history: /experts/history; query: none; required query: none. agent_activity: /agents/{agent}/activity; query: none; required query: none. |
project_threads | read | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. thread: /; query: none; required query: none. annotations: /annotations; query: none; required query: none. context_files: /context-files; query: none; required query: none. thread_jobs: /jobs; query: none; required query: none. |
project_exclusions | read | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. This tool has one operation and takes no action argument. exclusions: /exclusions; query: none; required query: none. |
project_studio_records | read | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. five_second_video_run: /five-second-video/runs/{run_id}; query: none; required query: none. generation_record: /generation-records/{asset_id}; query: none; required query: none. high_fidelity_3d_run: /high-fidelity-3d/runs/{run_id}; query: none; required query: none. high_fidelity_3d_sources: /high-fidelity-3d/sources; query: none; required query: none. media_capabilities: /media/capabilities; query: none; required query: none. media_gallery: /media/gallery; query: none; required query: none. media_spec_sheet: /media/spec-sheet; query: colourway, projection_type, state; required query: projection_type. model_approved_views: /model3d/approved-views; query: none; required query: none. model_versions: /model3d/versions; query: none; required query: none. product_sheet_latest: /product-sheets/latest; query: sheet; required query: none. video_briefs: /video-briefs; query: none; required query: none. video_script: /video-script; query: none; required query: none. texture_preferences: /model3d/texture-preferences; query: none; required query: none. visualization_dag: /visualization-dag; query: none; required query: none. visualization_readiness: /visualization-readiness; query: none; required query: none. visualization_references: /visualization-references; query: tag; required query: none. visualization_run: /visualization-runs/{run_id}; query: none; required query: none. visualization_clips: /visualization/clips; query: none; required query: none. visualization_scenes: /visualization/scenes; query: none; required query: none. visualization_stages: /visualization/stages; query: none; required query: none. media_objects: /media/objects; query: none; required query: none. visualization_clips returns ready candidates with measured_duration_s and Vault file/version identities. Review a finished clip, then project_studio_review(action=visualization_accept) keeps it in the Library. Its Background work result link opens Clips. Clips must remain off until the owner enables them. model_versions returns each saved run state, error_code, bounded error_message and retryable flag, including a failed newest attempt when an earlier accepted model remains available. Poll active work without commissioning another model. |
update_project | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. prefs: /prefs; body: prefs; required: prefs. core_topics: /core-topics; body: topics; required: topics. add_tag: /tags; body: text; required: text. pin_tag: /tags/{text}/pin; body: none; required: none. refresh_tags: /tags/refresh; body: candidates; required: none. |
update_project_context | spend | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. put_attributes: /attributes; body: editable project attributes; required: none. brief_field: /brief/{field_id}; body: value; required: none. title: /title; body: title; required: title. objective: /objective; body: objective; required: objective. |
refresh_project_summary | spend | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. abstract: /abstract; body: source, text; required: none. summary_retry: /summary/retry; body: none; required: none. |
project_lifecycle | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. archive: /archive; body: none; required: none. restore: /restore; body: none; required: none. templates: /templates; body: name, welcome_note; required: name. retry_import_source: /brainstorm-import:retry-source; body: none; required: none. |
clone_project | spend | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. This tool has one operation and takes no action argument. clone: /clone; body: none; required: none. |
project_expansion_run | spend | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. start_expansion: /expansion; body: expected_version, idempotency_key, passes; required: expected_version, idempotency_key. research_expansion: /expansion/research; body: accepted_ids, idempotency_key, question, revision; required: accepted_ids, idempotency_key, revision. Project expansion proposes typed technical entries alongside Idea text; review and accept entries before applying them. Research accepts an optional question; the saved query and accepted_ids stay with the run. Retry starts a new request with a new idempotency key and may use a narrower question; an identical network retry reuses its key. |
project_expansion_apply | spend | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. This tool has one operation and takes no action argument. apply_expansion: /expansion/apply; body: accepted_ids, idempotency_key, revision, source_hash; required: accepted_ids, idempotency_key, revision, source_hash. Project expansion proposes typed technical entries alongside Idea text. Apply writes one canonical invention-record revision; compatible selections still apply after an unrelated record change, and skipped, conflict or changed selections are reported. |
project_readiness_act | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. reconciliation_preview: /workflow/reconciliation/preview; body: content, expected_revision, note, source_hash, source_id, source_version; required: content, expected_revision, source_hash, source_id, source_version. reconciliation_apply: /workflow/reconciliation/apply; body: expected_revision, preview_hash, preview_id; required: expected_revision, preview_hash, preview_id. us_ids_applicability: /workflow/us-ids-applicability; body: applicability, expected_version, known_material, rationale, sources; required: applicability, expected_version, rationale. figure_applicability: /workflow/figure-applicability; body: expected_version, rationale, required; required: expected_version, rationale, required. |
project_readiness_run | spend | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. document_review: /workflow/document-review; body: artifact_ids, expected_version, idempotency_key; required: artifact_ids, expected_version, idempotency_key. prior_art_review: /workflow/prior-art; body: exclude_patents, expected_revision, idempotency_key, jurisdictions, limit; required: expected_revision, idempotency_key. |
project_binder_act | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. optional_ids must name registered optional logical IDs; retired or unknown selectors are refused. binder_prepare: /workflow/binder/prepare; body: format, idempotency_key, optional_ids; required: idempotency_key. binder_assemble: /workflow/binder/assemble; body: format, idempotency_key, optional_ids; required: idempotency_key. binder_import: /workflow/binder/import; body: expected_version, file_id, logical_ids, version_id; required: expected_version, file_id, logical_ids, version_id. |
project_research_act | spend | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. patent_search: /patents/search; body: claims, conversation_id, idempotency_key, jurisdictions, k, query; required: none. seed_topic_map: /research-plan:seed-topic-map; body: none; required: none. research_run: /research/runs; body: conversation_id, idempotency_key, mode, node_scope, scope; required: none. studio_prior_art_search: /studio/prior-art/search; body: claims, conversation_id, idempotency_key, jurisdictions, k, query; required: idempotency_key, query. |
project_watch_act | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. studio_prior_art_watch: /studio/prior-art/watches; body: agent, kind, label, rationale; required: label. watch: /watched; body: agent, kind, label, rationale; required: label. refresh_watch: /watched/{wid}/refresh; body: none; required: none. |
project_memory_generate | spend | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. This tool has one operation and takes no action argument. generate_memories: /memories/generate; body: none; required: none. |
project_memory_act | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. This tool has one operation and takes no action argument. memory_status: /memories/{mid}; body: status; required: status. |
project_document_exclusions_act | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. add_exclusion: /exclusions; body: text; required: text. rescan_vault_file: /vault/files/{fid}/rescan; body: none; required: none. |
project_participant_act | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. crew_settings: /roster/{agent}/settings; body: settings_override; required: settings_override. crew_expert: /roster/experts; body: area, expert_id, name; required: expert_id, name. crew_activate: /roster/{agent}/activate; body: none; required: none. crew_in_character: /roster/{agent}/in-character; body: on; required: on. crew_mute: /roster/{agent}/mute; body: none; required: none. crew_unmute: /roster/{agent}/unmute; body: none; required: none. |
project_thread_act | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. thread_patch: /; body: archived, pinned, title; required: none. composition_mode: /composition-mode; body: mode; required: mode. add_context_file: /context-files; body: file_id, folder_id, scope, version_id; required: file_id. sidebar_append: /sidebar/append; body: agent, branch_id, transcript; required: none. pivot_suggest: /pivot/suggest; body: reason; required: reason. |
project_side_conversation | spend | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. sidebar_message: /sidebar; body: agent, branch_id, prompt; required: agent, prompt. sidebar_retry: /sidebar:retry; body: agent, branch_id; required: agent. sidebar_dispose: /sidebar/disposition; body: action, branch_id; required: action. sidebar_dispose permits summary, conversation, record or thread; discard has a separate removal tool. |
project_card_act | spend | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. card_action: /actions; body: action, agent, one_shot, prompt; required: action, agent. annotation_action: /annotations/{proposal_id}/action; body: action, decision_id, destination, follow_up_text, option_id, option_text, selections, supersedes_decision_id; required: action. annotation_actions: /annotations/{proposal_id}/actions; body: action, decision_id, destination, follow_up_text, option_id, option_text, selections, supersedes_decision_id; required: action. A normal Project recommendation can have a saved typed normalized_proposal.record_update with expected_revision for the invention record and expected_attribute_version for project details; accept it with annotation_action and do not pass record_update in the action body. The response returns the updated record and attribute_version. batch_skill: /batch-skills; body: agent, label, prompt, skill_id, source_text; required: agent, label, prompt, skill_id. capability: /capabilities/{name}; body: agent, args; required: none. compact: /compact; body: none; required: none. contrib_summary: /contrib-summary; body: event_indexes, synthesis_index; required: event_indexes. |
project_studio_run | spend | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. visualization_run: /visualization-runs; body: board_ids, board_versions, colourway, controls, conversation_id, direction_starter_id, direction_starter_version, expected_description_version, form_preset_id, form_revision, idempotency_key, refine_direction, refine_from_candidate_id, role, state, style_preset_id, style_revision, take; required: expected_description_version, idempotency_key, role. product_sheet_run: /product-sheets/runs; body: board_ids, board_versions, colourway, conversation_id, correction_note, detail, expected_description_version, idempotency_key, sheet, state; required: expected_description_version, idempotency_key. high_fidelity_3d_run: /high-fidelity-3d/runs; body: controls, conversation_id, expected_description_version, idempotency_key, include_in_use, source_candidate_ids; required: expected_description_version, idempotency_key, source_candidate_ids. high_fidelity_3d_retry: /high-fidelity-3d/runs/{run_id}/retry; body: idempotency_key; required: idempotency_key. video_brief_run: /video-briefs/{brief_id}/runs; body: conversation_id, draft, idempotency_key, mode, model_candidate_id, resolution, revision, scene_candidate_id; required: idempotency_key, revision. canonical_model_run: /model3d/runs; body: controls, conversation_id, expected_description_version, idempotency_key; required: expected_description_version, idempotency_key. textured_model_run: /model3d/textured/runs; body: conversation_id, expected_description_version, idempotency_key; required: expected_description_version, idempotency_key. canonical_model_rebuild: /model3d/versions/{model_version_id}/rebuild; body: controls, conversation_id, expected_description_version, idempotency_key; required: expected_description_version, idempotency_key. abstract_stage_run: /visualization/stages/abstract; body: colour_direction, conversation_id, expected_description_version, idempotency_key, mood; required: colour_direction, expected_description_version, idempotency_key, mood. scene_run: /visualization/scenes; body: conversation_id, idempotency_key, lighting, model_candidate_id, stage_id; required: idempotency_key, lighting, model_candidate_id, stage_id. clip_batch_run: /visualization/clips/runs; body: conversation_id, expected_plan_revision, idempotency_key; required: expected_plan_revision, idempotency_key. model_render: /model3d/renders; body: conversation_id, idempotency_key, model_candidate_id, preset; required: idempotency_key, model_candidate_id, preset. five_second_video_run: /five-second-video/runs; body: conversation_id, idempotency_key, script_revision; required: idempotency_key, script_revision. five_second_video_retry: /five-second-video/runs/{run_id}/retry; body: idempotency_key; required: idempotency_key. visualization_retry: /visualization-runs/{run_id}/retry; body: idempotency_key; required: idempotency_key. media_render: /media/render; body: colourway, controls, conversation_id, projection_type, refine_delta, refine_from, state; required: none. media_model3d: /media/model3d; body: colourway, controls, conversation_id, projection_type, refine_delta, refine_from, state; required: none. media_video: /media/video; body: conversation_id, prompt; required: none. suggest_video_brief: /video-briefs/suggestions; body: describe_own; required: none. complete_studio_role: /visualization-readiness/complete-role/{role}; body: none; required: none. canonical_model_run starts Full detail work, then the server checks the GPU result in background jobs. Read model_versions or visualization_run for state and failure details; a queued request is not a finished model. textured_model_run builds simple shapes with colour bands and a still preview. Full detail uses the same durable background job and operation identity throughout: the server checks its saved run every 15 seconds, the GPU claims an API-owned lease through keyless callbacks and delivers the completed ZIP directly to the API. GPU heartbeats renew the lease every 30 seconds; after 90 seconds without one a later submission can recover the work. The job is complete only when the retained run is ready; clients read status rather than commissioning a second model. |
project_studio_cancel | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. high_fidelity_3d_cancel: /high-fidelity-3d/runs/{run_id}/cancel; body: none; required: none. five_second_video_cancel: /five-second-video/runs/{run_id}/cancel; body: none; required: none. visualization_cancel: /visualization-runs/{run_id}/cancel; body: none; required: none. |
project_studio_review | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. high_fidelity_3d_accept: /high-fidelity-3d/candidates/{candidate_id}/accept; body: none; required: none. high_fidelity_3d_reject: /high-fidelity-3d/candidates/{candidate_id}/reject; body: none; required: none. five_second_video_accept: /five-second-video/candidates/{candidate_id}/accept; body: none; required: none. five_second_video_reject: /five-second-video/candidates/{candidate_id}/reject; body: none; required: none. visualization_accept: /visualization-candidates/{candidate_id}/accept; body: none; required: none. visualization_reject: /visualization-candidates/{candidate_id}/reject; body: none; required: none. visualization_qa_override: /visualization-candidates/{candidate_id}/qa-override; body: none; required: none. product_sheet_approve: /product-sheets/{candidate_id}/approve; body: none; required: none. media_status: /media/objects/{mid}; body: status; required: status. media_status accepts status=accepted only; revocation uses unaccept_project_media. |
project_studio_save | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. set_media_role: /media-roles/{role}; body: candidate_id, expected_role_revision, media_object_id; required: none. texture_preferences: /model3d/texture-preferences; body: overrides; required: overrides. video_brief: /video-briefs; body: beats, camera, expected_revision, lighting, scene, story, template_id, title; required: beats, template_id, title. revise_video_brief: /video-briefs/{brief_id}; body: beats, camera, expected_revision, lighting, scene, story, template_id, title; required: beats, template_id, title. approve_video_brief: /video-briefs/{brief_id}/approve; body: expected_revision; required: expected_revision. video_script: /video-script; body: beats, direction, expected_revision, source_candidate_ids; required: beats, expected_revision, source_candidate_ids. approve_video_script: /video-script/approve; body: expected_revision; required: expected_revision. visualization_reference: /visualization-references; body: file_id, tag, version_id; required: file_id, tag, version_id. clip_plan: /visualization/clips/plan; body: expected_revision, shots; required: expected_revision, shots. set_media_role needs media_object_id or candidate_id; clearing uses clear_project_media_role. |
remove_project | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. This tool has one operation and takes no action argument. project: /; the removal body is fixed by the tool. |
remove_project_tag | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. This tool has one operation and takes no action argument. tag: /tags/{text}; the removal body is fixed by the tool. |
remove_project_watch | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. studio_prior_art_watch: /studio/prior-art/watches/{wid}; the removal body is fixed by the tool. watch: /watched/{wid}; the removal body is fixed by the tool. |
remove_project_memory | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. This tool has one operation and takes no action argument. memory: /memories/{mid}; the removal body is fixed by the tool. |
remove_project_exclusion | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. This tool has one operation and takes no action argument. exclusion: /exclusions/{eid}; the removal body is fixed by the tool. |
remove_project_thread | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. This tool has one operation and takes no action argument. thread: /; the removal body is fixed by the tool. |
remove_project_context_file | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. This tool has one operation and takes no action argument. context_file: /context-files/{fid}; the removal body is fixed by the tool. |
remove_project_participant | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. This tool has one operation and takes no action argument. crew_deactivate: /roster/{agent}/deactivate; the removal body is fixed by the tool. |
remove_project_scene | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. This tool has one operation and takes no action argument. studio_scene: /visualization/scenes/{candidate_id}; the removal body is fixed by the tool. |
remove_project_media | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. This tool has one operation and takes no action argument. studio_media: /media/objects/{mid}; the removal body is fixed by the tool. |
unaccept_project_media | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. This tool has one operation and takes no action argument. media_unaccept: /media/objects/{mid}; the removal body is fixed by the tool. |
clear_project_media_role | write | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. This tool has one operation and takes no action argument. clear_media_role: /media-roles/{role}; the removal body is fixed by the tool. |
discard_project_side_conversation | spend | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. Spend permission is required because the existing API route also serves commissioning operations; this tool submits only the confirmed removal and starts no model work. This tool has one operation and takes no action argument. sidebar_discard: /sidebar/disposition; the removal body is fixed by the tool. |
undo_project_annotation | spend | Use project_id for project routes, or conversation_id for thread routes; the API enforces ownership. Take conversation_id from read_project. Put path identifiers in ids. Preserve returned revisions and idempotency keys when retrying. Ask the member for confirmation before calling. This tool also requests confirmation where the client supports it. Spend permission is required because the existing API route also serves commissioning operations; this tool submits only the confirmed removal and starts no model work. annotation_undo: /annotations/{proposal_id}/action; the removal body is fixed by the tool. annotation_undos: /annotations/{proposal_id}/actions; the removal body is fixed by the tool. |
create_project_thread | write | Create or resolve a thread for the named project through its signed-in API. Needs session and project_id. Starts no model work. |
resolve_project_thread | write | Create or resolve a thread for the named project through its signed-in API. Needs session and project_id. Starts no model work. |
This release maps 156 of 166 audited project routes; ten have permanent exclusions. unaccept_project_media, clear_project_media_role and discard_project_side_conversation have idempotentHint=false: read current state before retrying after a lost reply. undo_project_annotation and discard_project_side_conversation require Spend permission because their shared routes can commission other actions; these removal calls invoke no model.
Documents, references, web sources, consultations, the knowledge map, the Vault, the library and project drafts.
| Tool | Scope | What it does |
|---|---|---|
vault | read | List a scenario or project Vault after open_session. Pass exactly one of scenario_id or project_id. A project also returns its folders. Free. The listing supplies file and version IDs for resources; scenario vault_object_id is used for linking. |
link_vault_object | write | Link an existing Vault object after open_session and selecting a scenario. Find vault_object_id in vault; scope is scenario, shared or thumbnail. Free. |
unlink_vault_object | write | Unlink a Vault object after open_session and selecting a scenario. Find vault_object_id in vault. Removes only the association, never the file. Free. |
upload_vault_object | write | Upload a file to a scenario or project Vault after open_session. Pass exactly one of scenario_id or project_id, filename, its bytes as content_base64 and optional content_type. Free; the default local cap and API landing limit are 15 MiB. The API owns storage and validation. Read vault afterwards for file/version IDs and the file resource; do not repeat an upload merely to poll its status. |
vault_object_act | write | Rename or move a project Vault file after open_session and vault(project_id). Actions: rename needs name; move needs folder_id. Pass file_id from the Vault. Free. Use delete_vault_object to remove a file. |
delete_vault_object | write | Remove one project Vault file after open_session and vault(project_id). Needs file_id. Ask the member first; deletion removes the file and its versions. The API applies ownership and retention checks. |
knowledge_map | read | Read the canonical knowledge graph after open_session and selecting a scenario. Use action subgraph with a root_id from read; depth, nodes, links and fanout bound the result. Export accepts revision. Reads and exports are free. The API reports disabled features or unavailable revisions. |
refresh_knowledge_map | spend | Refresh the canonical knowledge graph after open_session and selecting a scenario. Can queue metered alignment; read knowledge_map afterwards. The API reports disabled features. |
knowledge_disposition | write | Record a knowledge review after open_session and knowledge_map. record_type is knowledge_item, knowledge_statement, knowledge_work_item or knowledge_relationship; record_id comes from the graph. Set epistemic_state and optional review or lineage fields. Free; the API validates states and retains review history. Reuse an explicit client_request_id to retry the same disposition safely. |
shared_gap_lifecycle | write | Update a shared knowledge gap after open_session and reading the graph or frame coverage. Pass shared_work_item_id and action record_answer, propose_closure, confirm_closure or reopen. Evidence uses existing evidence_anchor_ids; reopen needs a reason. Free; the API decides the resulting gap and linked-slot states. |
document_export | write | Build a docx or pdf export from a completed document run after open_session. The API builds and stores the file during this call; no model call is needed. An existing export is returned as saved. When document_run lists the format in obsolete_exports, pass refresh=true to render the same saved text again with the current layout as a new file; the earlier file is kept and a repeat converges. Returns the existing run_id, pollable with document_run, and the built file's ipguru://scenarios/<scenario_id>/documents/<run_id>/<format> resource. The API controls availability and free-tier PDF watermarking. |
upload_reference | write | Upload a document as a scenario or project reference after open_session. Give exactly one of scenario_id and project_id. Pass filename, its bytes as content_base64 and optional note; evidence_for is scenario-only. source_url is for a saved HTML page. The default limit is 15 MiB. The returned run_id is the reference_id: pass it to read_reference, or find it with list_references. A project upload can queue source description when the grant allows spend; otherwise the file remains in the Vault with skipped_work. Use read_reference to check the result. |
read_coverage | read | Read what the scenario has covered and what remains after working on the idea. Needs open_session and a scenario; documents true includes document coverage. Free. |
library | read | List or read library entries after open_session. Read needs entry_id from the list. Free. |
library_act | write | Publish a scenario Vault object, replicate a library entry into a scenario, or designate its replica after open_session. Find vault_object_id with vault and entry_id with library. Publish needs scenario_id and vault_object_id; replicate needs scenario_id and entry_id; designate needs entry_id and replica_id. Free. Publishing shares the file through the library. |
unpublish_library_entry | write | Unpublish a library entry after open_session and library. Needs entry_id; optional title names the confirmation. Removes the shared entry and asks before acting where the client can ask. Free. |
read_references | spend | Start reading prepared references after list_references shows they are ready. Needs open_session and exactly one of scenario_id or project_id; omit reference_ids to read all ready references. Runs a model and is metered; poll the returned run_id with reference_read_run. |
reference_read_run | read | Poll a run_id from read_references in the same scenario or project. Needs open_session and exactly one of scenario_id or project_id. wait_s waits up to 45 seconds with progress. Free; read_reference(answers=true) shows the answers when complete. |
canonical_sites | spend | Recommend sources, suggest a URL as an unapproved candidate, or crawl a reviewed selection. Needs open_session and a scenario; suggest needs url and optional note; crawl needs source_ids or sites the member has reviewed. Suggesting is free; recommendation and crawling may run a model and are metered. Poll a returned job_id with knowledge_job; read_knowledge shows the source state. |
list_consultations | read | List a scenario's saved expert consultations, optionally filtered by kind. Needs open_session and a scenario; use read_expert_consultation for a result. Free. |
run_consultation | spend | Commission critique, perspective, sales, stress_test or voc after choosing a scenario. Critique and stress_test take one to five reviewer_ids; perspective takes exactly one profile_ids entry and at least one frame_keys entry; voc takes exactly one profile_ids entry; sales takes up to eight profile_ids. Needs the card's revision. Runs a model and is metered; returns a job handle to poll with consultation_job, then read_expert_consultation. Omit kind to choose; this asks before acting where the client can ask. Clients without choices need an explicit kind. |
consultation_job | read | Poll the job from run_consultation or consultation_act, or list jobs by kind and subject_key when job_id is omitted. Needs open_session and the same scenario. wait_s waits up to 45 seconds with progress for one job. Free; read_expert_consultation after completion shows the findings. |
read_expert_consultation | read | Read findings and recommendations after consultation_job completes or after list_consultations. Needs open_session, the scenario and consultation_id. Free; read the card's revision before acting on findings. |
consultation_act | spend | Act after read_expert_consultation: act_findings needs finding_ids and finding_action; finding_action is adopt, suggest, park, dismiss, discuss, debate or choose. act_recommendation needs recommendation_id and recommendation_action (accept or decline); accept needs a free expert seat or returns brainstorm_expert_slots_full. append_suggestions needs suggestion_ids from finding_id or recommended_action.action_id, not the output's suggestion_id labels. These are free. regenerate and generate_instrument run a model and return a consultation_job handle; the instrument is for voc and needs its consultation_revision. Every action needs the card's revision and open_session. |
list_documents | read | The document actions available to this scenario at the account's tier, with the runs and artefacts so far. Free. |
start_document | spend | Start a document run for an action_id from list_documents, optionally revising an earlier run (revises_run_id). A job: returns the run id; poll with document_run. Metered by tier. Omit action_id to choose an available pack; this asks before acting where the client can ask. Clients without choices need an explicit action_id. |
document_run | read | Poll a document run by id after open_session. wait_s waits up to 45 seconds with progress. Free. |
document_artifact | read | Read a finished run's artefact. kind markdown returns the text; Word and PDF return a resource link to the built file, also available in the app's Documents. Free. |
document_act | spend | Act on a document run: accept it, revise it (with notes; a job, poll document_run), cancel a running one, or dismiss a finished one. Free except revise. |
list_references | read | List a scenario's or project's references with relevance. Give exactly one of scenario_id and project_id after open_session. |
search_references | spend | Search for references answering a question, optionally from one source_url. Give exactly one of scenario_id and project_id. A project may set for_corpus to include a ready result in an assessment corpus. Returns the reference id; poll with read_reference. |
read_reference | read | Read a reference after list_references or search_references. content true includes its source content; answers true includes its extracted answers. Needs open_session and the same scenario or project. Give exactly one of scenario_id and project_id. |
file_project_chosen_ideas | write | File the ideas chosen in the project’s saved start record into Source material once its Vault is ready. Repeating returns the retained references. Read list_references next. |
file_project_chosen_ideas | write | File the ideas chosen in the project’s saved start record into Source material once its Vault is ready. Repeating returns the retained references. Read list_references next. |
add_web_page | spend | Add one public web page (HTML or PDF, up to 15 MB) as a scenario or project source by its address. The server reads that page only, from a public address: private or internal addresses, sign-ins and the rest of the site are refused. Returns the reference id; poll with read_reference. A page filed as a challenge kind is then read for its criteria in a scenario; see read_challenge_fit. Give exactly one of scenario_id and project_id. |
read_challenge_fit | read | Read how the Idea fits the challenge it answers: each challenge document (rules, brief, call or platform guidelines) with its criteria in document order, the document's own quotation and locator, each criterion's fit state and reason, and counts by state. There is no total or percentage, and the fit never changes the Idea score. goal_questions are the criteria that stand in for a goal's standard questions. Needs open_session and a scenario. Free. |
check_challenge_fit | spend | Check the Idea against one challenge document again, by reference_id from read_challenge_fit. Reads its criteria first when they are missing, failed or out of date. A job: returns job_id; poll with read_challenge_fit until that document's fit state is current or failed. Needs open_session. Metered. |
reference_act | spend | Act on a reference: relevance (explain one citation by citation_index), retry a failed fetch or search, note (title, note, scenario-only evidence_for), set source_kind from catalog(source_kinds), or mine its contents. source_kind null clears classification; mine requires a kind first. Needs open_session and a reference from list_references. Give exactly one of scenario_id and project_id. |
remove_reference | write | Remove a reference after open_session and list_references. Give exactly one of scenario_id and project_id, plus reference_id; optional title names the confirmation. Asks before acting where the client can ask. |
read_knowledge | read | The scenario's knowledge map. Free. |
generate_topic_map | spend | Generate the topic map. A job: returns the job id; poll with knowledge_job; read the map with read_knowledge when the job is done. Metered. |
knowledge_job | read | Poll a topic map job by id from generate_topic_map. Read the completed map with read_knowledge. wait_s waits up to 45 seconds with progress. Free. |
read_consultation | read | Read the seated crew and their consultation state after selecting a scenario. For the expert consultations see list_consultations. Needs open_session. Free. |
disclosure | read | Read the member's account-wide disclosure log after open_session. List returns saved entries; bearing and offers need scenario_id and return subject overlap or mined offers, without judging patentability or legal deadlines. Deterministic and free. |
disclosure_act | write | Create or update the member's account-wide disclosure log, or accept_offer or decline_offer after open_session and disclosure. Create records only the facts and dates the member supplies. Update needs disclosure_id; omitted fields stay unchanged and empty strings/lists clear optional fields. accept_offer records the member's confirmed facts for reference_id; decline_offer records their refusal. All actions are deterministic and free; create has no retry key. |
delete_disclosure | write | Permanently remove one entry from the member's account-wide disclosure log after open_session and disclosure. Needs disclosure_id. Removes only that log entry. Deterministic and free. |
project_draft | spend | Prepare the current scenario's editable Project Wizard source after open_session and read_scenario. Reuses a revision-pinned import when enabled; otherwise returns the API's legacy draft. Deterministic, with no model generation. Read the returned import_id before refresh_project_import; submit it with create_project. |
refresh_project_import | spend | After project_draft, refresh its import_id against the latest scenario. Returns the API's bounded diff without overwriting Wizard edits. Deterministic, no model call. Needs open_session; preserve disabled-snapshot or ownership refusals. |
publication_import_draft | read | Read your private import draft for a published template slug after open_session. Free. Review the draft before save_publication_import_draft or publication_import_act(create). All state lives in the API. |
save_publication_import_draft | write | Save your private import draft after open_session and publication_import_draft. Pass expected_revision and the reviewed edition, seed/full mode, name, seed fields and open_in_expand choice. Replaces these choices; it does not import or generate anything. Free. Use publication_import_act(create) only after reviewing the draft. All state lives in the API. |
publication_import | read | Read an existing private publication import after open_session. Pass import_id from publication_import_act(create). A completed copy is not an assessed idea or a model-generated expansion. Free; preserves lifecycle and ownership refusals. |
publication_import_act | spend | Create a private copy from the published slug and reviewed edition/seed/full choices after open_session and publication_import_draft. Create queues provisioning and import work, returning import_id; publication_import follows that existing import. A completed copy is not an assessed idea or a model-generated expansion. Retry resumes only an API-permitted failed import after you inspect its reason; a terminal import is returned unchanged. Cancel stops the import and archives its retained private copy. Keep the returned create idempotency_key and preserve quota, lifecycle and ownership refusals. No direct model call; downstream work stays under the API's limits. |
Studio descriptions, art direction, shoot lists and image runs.
| Tool | Scope | What it does |
|---|---|---|
read_studio_workspace | read | Read capabilities, boards, work, one work item, its history or saved content after open_session. Pass exactly one of scenario_id or project_id and choose action: capabilities, boards, work, item, history or content. For the last three use work_id, and for content also output_id. Free; use the returned revisions with studio_workspace. |
studio_workspace | spend | Create or update a reference board, create Studio work, or send a work command after open_session and read_studio_workspace. Pass exactly one of scenario_id or project_id. Actions: create_board, update_board, create_work, command. Supply the API's request fields in body, board_id for update_board, or work_id for command. Commands can start sheet and picture runs; poll with read_studio_workspace. The API applies the account's and project's gates. |
approve_studio_description | write | Approve the current project description draft after open_session and read_studio. Pass its expected_version and expected_context_revision from read_studio. Repeating approval of an approved draft changes nothing; the API refuses stale versions. |
studio_run | spend | Commission turnaround, detail_sheet, take, model3d or video after open_session and read_studio. Save a current description first and pass its revision; take also needs a shot key, with phase/component/direction where required; turnaround takes a sheet from read_studio's catalogue sheets (default product_sheet). Media uses prompt. Metered by tier; reuse idempotency_key to retry the same request. Poll the returned run_id with studio_run_status; never start a replacement to poll. |
studio_run_status | read | Read Studio and media runs after open_session, or poll the run_id from studio_run or shoot_list(run). Free. wait_s waits at most 45 seconds with progress, then returns still_running with the last state. Ready image runs include resource URIs. needs_input or needs_review requires attention; unavailable is terminal and preserves the API's provider refusal. Do not start a replacement generation automatically. |
studio_run_act | spend | Dismiss a failed Studio run, cancel an unfinished image run, or retry a failed media run after open_session and studio_run_status. Dismiss and cancel are free; work already sent to the image provider may still be charged, and a settled run is returned unchanged. Retry is media-only and can incur provider costs. The API decides whether its persisted state permits the action. |
studio_candidate | write | Approve a turnaround or accept a candidate after open_session and read_studio. Inspect the image resource and quality result first. Free. Approval and selection remain subject to the API's currentness, scope and quality checks. |
dismiss_studio_candidate | write | Dismiss a Studio candidate after open_session and read_studio. Needs candidate_id. Removes the image from its gallery and roles, with no restore route. Free. |
read_visual | read | Read the scenario's compatibility visual description after open_session. Free; read_studio has the full Studio record. |
set_visual | write | Save the compatibility visual fields after open_session and read_visual. Pass the current scenario revision and all five fields; omitted fields become empty. Free. |
generate_image | spend | Request an image through the compatibility visual action after open_session and read_visual, passing the current scenario revision. Metered; the API's queued result and any missing-description or tier refusal are returned unchanged. |
read_studio | read | Read a scenario's Studio record or a project's physical description after open_session. Pass exactly one of scenario_id or project_id. Free. Use its revision or expected_version for edits; a project draft is approved with approve_studio_description. |
studio_description | read | Read a scenario or project Studio description history after open_session and read_studio. Pass exactly one of scenario_id or project_id. Free. |
studio_description_act | spend | Set or generate a Studio description after open_session and read_studio. Set commits a new description version at once; it needs document in the record's description shape, pending questions and its revision. Generate writes its result into the description draft (read_studio draft), which the next product sheet locks as a version; it needs parts and current, optionally an instruction, and uses a metered model. For a project pass project_id alone, data and both expected_version and expected_context_revision from read_studio to set the single open draft. Editing an approved description opens its next version; subsequent edits keep that draft version. Generate needs the same revisions and part (all or a named family section), optionally revision_request. Restore needs source_version from history and the same current revisions; it copies into the open draft without changing historical evidence. Legacy calls without expected_context_revision retain their append/derive behaviour. Set is free. Read history with studio_description; approve project drafts with approve_studio_description. |
read_project_art_direction | read | Read a project's saved look, pinned Style guide, scene settings, default setting and allowed art direction options after open_session. Free. Use its revision with set_project_art_direction or remove_project_scene_setting. |
set_project_art_direction | write | Save a project's look after read_project_art_direction. Pass its revision as expected_revision, the six art_direction fields, the pinned design_guide {id, version} or null, all scene_settings and default_scene_setting ID or null. Settings have stable id, label, setting, actor, backdrop and source (member or use_case). Preserve existing setting IDs; removing one needs remove_project_scene_setting. Free; stale revisions are refused. Product sheets stay neutral; other pictures and model-based scene stills use this look. |
suggest_project_scene_settings | spend | Draft project scene settings from the latest saved description's use cases after open_session and read_project_art_direction. Uses a metered model. Returned settings are proposals; review them, then keep or edit them with set_project_art_direction at the saved record's current revision. This does not create model-based scenes or start pictures. |
remove_project_scene_setting | write | Remove one saved scene setting after read_project_art_direction. Pass setting_id and the returned revision as expected_revision. Free; stale revisions are refused. Removing the default clears its selection. Earlier pictures remain saved. Use set_project_art_direction for additions or edits. |
set_art_direction | write | Save the Studio art direction after open_session and read_studio. Pass the record's art_direction shape and revision; its options show allowed choices. Free. The API refuses stale revisions. |
suggest_studio_settings | spend | Suggest settings for a shot after open_session and read_studio. Pass the shot key and current revision. Uses a metered model; read the suggestions before saving art direction or the shoot list. |
shoot_list | spend | Set or run the shoot list after open_session and read_studio. Set passes shots with shot, optional direction (setting, actor, backdrop, note), phase and component. Use revision and expected_list_revision from the record. Set is free; run queues metered images; retry runs again only the shots of the last run that produced no picture. Reuse idempotency_key for a retry; poll studio_run_status. |
set_studio_role | write | Seat a reviewed candidate in a Studio role after open_session and read_studio. Pass role and candidate_id from that record. Free; stale, cross-scope or unapproved selections retain the API's refusal. |
Director setup, plans, runs and evidence for a scenario or project. Pass exactly one of scenario_id or project_id where supported; question, ask and apply actions remain scenario-only. The project gate comes from the API. On the main address and on /mcp/director.
| Tool | Scope | What it does |
|---|---|---|
director_questions | read | List a scenario's Director questions after open_session. Free. Use ask_director_question to record an ask for a selected run and step. A project_id is refused: review project proposals on the Invention page's Pending review and in the Register; answer a run question with director_control(answer). |
ask_director_question | spend | Record a scenario Director question ask after open_session and director_questions. Needs run_id and step_id; may include question_key or custom_question_id from the list, and returns its occurrence. Recording an occurrence is free; continuing answer work is metered. A project_id is refused: review project proposals in Pending review and the Register, and use director_control(answer) with objectives {question, text} for inventor input. Respond only resumes; it never supplies an answer. Reuse the returned idempotency_key on retries, or supply one before the first ask. |
director_run_status | read | Read a scenario or project run after approval. With no run_id, uses the newest active run or latest finished run; returns run:null when none exists. Free. wait_s caps at 45 seconds and adds wait_exhausted when the wait ends. Commissioned studio_work_pending, reference_work_pending, consultation_work_pending, expansion_work_pending and project_work_pending resume automatically when work finishes; ready_to_advance waits for the member to advance the project stage. A posted question can still be recorded with director_control(answer) without resuming it. Read other parked reasons before using director_control(resume). A project supervised review resumes after the member has reviewed proposals in Pending review and the Register; Resume accepts none of them. Never treat parked work as completed. The compact view keeps limits, outcome, required input and actions; use read_director section=run for details. budget_exhausted and budget_exhausted_unmet mean the work limit was reached. |
director_control | spend | Control a scenario or project run using run_id and revision from read_director or director_run_status. Pause and cancel_to_manual stop work without a model call; resume, restart, reset_objectives and other permitted actions may queue metered work. Stop/cancel mean cancel_to_manual; respond means resume. In a loop review, the actions are apply (scenario, through director_apply) and cancel_to_manual; project proposals are reviewed in Pending review and the Register, then the member can Resume without accepting them. For an open question, answer with objectives {question, text}. step_mode {enabled}, add_allowance {max_loops, new_research, time_seconds}, steer {criterion_id} and skip_route {route_id} retain their run controls. Reuse command_id on retries; API transition and revision refusals pass through. |
director_apply | spend | Apply reviewed scenario Director candidates after review_ready and read_director_evidence. Pass run_revision and only the selected_candidates you accept, including reviewed Studio candidates in supervised mode. Can start metered work. A project_id is refused: project work creates proposals for the Invention page's Pending review and the Register; neither this tool nor Resume accepts them. Preserve the returned idempotency_key on retry. API source, revision and Studio refusals pass through. |
read_director_evidence | read | Read a scenario or project Director run's evidence after open_session, using run_id from read_director. Free; returns the page and cursor unchanged. Follow the returned cursor for further pages; default limit is 50. |
read_director | read | Read bounded scenario or project Director state after open_session. Default summary shows saved setup revisions, plan/run summaries, limits and the application URL. Sections setup, criteria, sources, capabilities, plan and run expose exact API data as paged fields. plan/run need their saved ID; plans/runs page history. Follow $detail.path using the same section and ID; next_cursor continues that path. Free; retain returned revisions and reread before changing them. |
director_criteria | spend | Save scenario or project completion criteria after read_director for free, using the current criteria draft revision. Scenario suggest runs a metered model, needs current scenario_revision and idea_revision, and can regenerate one criterion with criterion_id. Project suggest refreshes unmet required criteria from the current stage verdict without a model call and retains member-added criteria; it does not regenerate a member criterion. Pass criteria objects and rejected_ids when saving. A project criterion can carry attach_stage; pass returns_allowed when saving project criteria. Use command_id to identify a retry. To detach an attachment, use the separate detach_director_criterion tool. |
detach_director_criterion | write | Detach one project Director criterion attachment using project_id, attachment_id and reason. Ask the member first. This is a project-only removal, separate from director_criteria; it does not run a model. Read the Director and stage verdict again to see the detached state. A writable project may detach regardless of the Director run gate. |
director_plan | spend | Create a scenario or project Director draft from a goal, or approve a reviewed plan_id and revision. Create is free; approval starts metered work. Read Director limits and criteria first, then show the returned draft before approval. For a project, an omitted returns_allowed inherits the saved setup; save that switch with director_setup first. Plan criteria can carry attach_stage; stage_work follows the current project stage and API gate. For a scenario, missing theme/frame snapshots come from the scenario and the question program uses the current catalog unless supplied. If create includes limits or context, first save them with director_setup and pass its setup_revision; otherwise the tool refuses without sending a request. With setup_revision, saved setup is authoritative. An approve conflict director_run_active names the active run_id: read it with director_run_status, or stop or restart that run first. Use supervised mode to review candidates. Supply command_id before the first create or approve and reuse it for the same request after a lost reply. |
director_setup | spend | Save scenario or project Director setup or prepare selected sources after read_director. Use the setup revision and retain command_id for a retry; one is returned when omitted. Save is free and accepts the named setup step and structured settings; pass returns_allowed when saving the project switch. prepare_sources may enqueue metered reading; criterion_id narrows that work. Read the preparation state before plan creation, and pass setup_revision when creating a plan with limits or context. |
detach_director_criterion has readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=false. The ten existing Director tools keep their permission hints.
Public examples on ipguru.ai. For IPGuru administrators who own the scenario. On the main address only.
| Tool | Scope | What it does |
|---|---|---|
read_publication | read | Inspect saved publication status and capability, free, administrator owner only. section selects status, draft, inventory, preparation, editions or audiences. Large sections are JSON text pages; follow next_offset with view_digest to detect changes. status includes the confirmed live edition and URL; it does not imply the pending update is live. No models run. Preparation progress is persisted; read again to poll without keeping this client connected. |
configure_publication | write | Save a public-example selection at its current expected_revision. Select only the material the user wants public. Free; does not prepare or publish. advance_original defaults false: enable only when further development was requested. Read the returned revision before the next mutation; after a lost response inspect the saved draft rather than blindly writing again. |
prepare_publication | spend | Start durable, metered public-edition preparation from the saved selection. Supply expected_revision and a stable idempotency_key before the first call; reuse that key after a lost response. Poll read_publication(preparation). This commissions work and does not publish or approve a public edition. |
continue_publication_preparation | spend | Resume or retry the existing preparation at its saved revision. May resume metered work; does not publish. Read current preparation state/revision after a lost response before issuing another control. |
stop_publication_preparation | write | Pause or cancel only this public-edition preparation at its saved revision. No new model work. Existing completed artifacts and any live edition remain. Read preparation state after a lost response before repeating. |
preview_publication | write | Freeze the selected public edition for review. Free; does not publish. Returns preview_id and candidate edition_id/digest bound to exact bytes. Review its file list and read_publication_asset, obtain the user's explicit decision, then publish with the returned identities. Changed source or selection requires a fresh preview. After a lost response inspect editions and make a fresh preview; never guess an approval identity. |
publish_publication | write | After the user approves the exact frozen edition, apply its preview_id, edition_id and digest with a caller-stable idempotency_key. Pass the reviewed selection and current revision, without adding unreviewed material. Free; queues publication and returns persisted status, not a success claim. Poll read_publication until live_edition_id matches this edition and status is published. A failed update preserves the prior live edition. |
retry_publication | write | Retry the existing failed publish/withdraw journal at its current revision. Free; reuses the reviewed edition and does not regenerate or approve new material. Poll status; inspect state after a lost response before repeating. |
preview_publication_withdrawal | write | Create the required withdrawal preview. Free; no withdrawal yet. Review the consequence with the user, then pass preview_id to withdraw_publication. Previously completed recipient copies are retained. |
withdraw_publication | write | Withdraw after the user's decision using the withdrawal preview_id and a caller-stable idempotency_key. Free; retains completed recipient copies. Poll persisted publication status to confirm withdrawal; reuse the same key after a lost response. |
read_publication_asset | read | Read exact private frozen edition bytes by key from its file list. Free. Returns bounded base64 chunks, total bytes and SHA-256; follow next_offset to read the whole file. Authentication/owner checks run on every chunk. The authenticated URL contains no token and is not a public preview copy. |
Errors
IPGuru passes the app's own messages through unchanged, so they can be shown to the member as they are.
| Answer | Meaning |
|---|---|
| HTTP 401 | No token, or the connection was revoked or expired. Sign in again. |
scope_required | The connection lacks the scope this tool needs. |
| A rate-limit error | Too many requests on this connection. Slow down and try again. |
| A conflict or stale revision | The record changed since the client read it. |
| An allowance or membership refusal | The member's membership does not cover the action. Do not retry. |
| An unknown session | Call open_session again. |
| This connector call could not be recorded | IPGuru could not record the call, so it did not start it. Try again later. |
This page describes connector version 0.48.0. Questions: contact us.