person tools

​

person_attach

Tier: write · Tags: person, write Enrich one existing private person with extra grounding - exactly one of source / evidence. Use this to add hand-tailored material to a single Person after the fact (vs. person_generate, which mints N people from a brief / sources). See docs_get("guides/build-specific-person") for the evidence loop.

• source=SourceAttachInput(path=..., description=...) runs the Person-scoped 3-step attachment intake (initiate → signed-URL PUT → confirm) - a file you want this Person to react to.
• evidence=[EvidenceTraceInput(...), ...] POSTs scenario answers the Person’s simulation-time prompt reads as <past_reactions>.

The Person must be private (visibility="private"): the backend rejects shared/published people (moderation gate); the MCP surfaces that as [validation_error] with a “must be private” message. person_id: UUID or short alias (e.g. p-d4e); must be a caller-owned private Person. source: file payload - exactly one of source / evidence. evidence: 1..N EvidenceTraceInput rows (mutually exclusive with source). Each carries text (the Person’s answer), source enum (situation / voice / binary / micro-story), scenario_prompt (the question), optional raw_response. Returns PersonAttachResponse: with source, success sets attachment_id; with evidence, evidence_traces lists the persisted rows. Full shape: docs_get("reference/responses").

​

Parameters

​

person_delete

Tier: destructive · Tags: delete, person Permanently delete a person. DESTRUCTIVE. Public-pool people cannot be deleted by individual workspaces; the backend rejects those with [auth_failed] (or [not_found] if the Person does not exist). person_id: UUID or short alias (e.g. p-d4e) of the person to delete. Returns {"deleted": True, "person_id": <id>}.

​

Parameters

​

person_generate

Tier: long-running · Tags: dispatch, person Mint new simulated people from a plain-English brief (“three skeptical indie hackers”, “a head of product at a Series B”) and optional research files, via the agentic generation pipeline. Returns the minted person_ids, which you pass as people.person_ids on study_run / ask_run. Bills credits per person actually produced, more with avatars; live rates in account_usage().rates. workspace_id: UUID or short alias (e.g. w-6ec) of the workspace. description: free-text brief for the people to mint (>=20 chars when supplied). source_paths: evidence references - prefer a data: URL or an http(s):// URL (fetched server-side, SSRF-guarded, 10MB cap). A local file path is read from the MCP server’s own filesystem, so it only helps when you run the server yourself. source_upload_ids: reuse sources already uploaded via source_upload (or a prior partial build) without re-uploading. reaction_notes: one researcher note per source_paths entry (same order, same length) describing how the real person reacted to THAT artifact; "" skips a note for that file. count: pin how many to mint, [1, 10]; omit to let the agent propose. age_range: (min, max) inclusive. country: ISO-3166-alpha-2 codes. gender: list of gender labels. generate_evidence: also produce grounded EvidenceTrace rows. None (default) = auto (scenarios only when sources attached); True / False override. job_id: resume mode - poll an already-enqueued job instead of starting one. Returned in next_action by a wait=False call. Mutually exclusive with every generation input: combining them is a validation_error, never a silent discard. wait: bool, default True - blocks until terminal (runs take ~30-60 s). False returns the job_id immediately plus a next_action naming the resume call. timeout: float seconds to wait when wait=True; default 180. Minting also counts toward the plan’s custom-person entity cap, which is independent of the credit pool; on hit, [usage_limit_reached]. Uploaded evidence - emails, PDFs, text, images, audio - grounds the people it mints, optionally with scenarios traced back to the real reactions. See docs_get("concepts/person") (generate vs manual) and docs_get("concepts/source") (artifacts as generation inputs). Blocking and resume. wait=True uploads artifacts, enqueues the job, polls to terminal, returns resolved people + scenarios. person_generate(workspace_id=..., job_id=...) re-attaches to that same job and waits it out. See docs_get("reference/long-running-jobs"). The three inputs (description, source_paths, source_upload_ids) freely combine. Combining job_id with any of them is a validation_error rather than a silent discard; if the job is already terminal, wait=False returns the same envelope the blocking call would have - the minted people on completed, ok=False otherwise - with no next_action. source_paths in full. data: and http(s):// URLs are portable and work against the hosted server. To feed raw local bytes to the hosted server, upload them first with source_upload(inline_base64=...) and pass the returned id via source_upload_ids. Supported MIME: audio/*, image/*, text/*, application/pdf, application/json, office-document types. Single-person role-fitting (pair-mode use case). Pair-mode chat rehearsals (study_add_iteration with chat_pair=...) need one person per side: call person_generate(count=1, description="...") per side; the returned ids plug into ChatPairConfig.group_a / group_b. Pipeline-specific failures come back as generation_failed or timeout. Partial-failure contract: when upload(s) succeeded but enqueue failed, source_ids is still populated so agents can retry against existing sources without re-uploading. Returns PersonGenerateResponse keyed by ok: wait=True populates people + person_ids, wait=False job_id + status="queued" + next_action. Full shape: docs_get("reference/responses").

​

Parameters

​

person_get

Tier: read-only · Tags: person, read Read people. Polymorphic on person_id: omit to list, pass it to fetch one Person. workspace_id: UUID or short alias (e.g. w-6ec) of the workspace. person_id: UUID or short alias (e.g. p-d4e); omit to list. scope: which pool to list - "workspace" (default, this workspace’s own people), "platform" (the admin-curated public pool), or "all". The same three values as the run verbs’ people.scope. visibility: raw backend filter; wins over scope when both are set. "workspace" | "shared" | "platform"; "private" / "public" are accepted deprecation aliases for the first and third. type: "ai" (default, simulatable) | "human" | "all". limit: int, default 50, max 200. offset: int, default 0. search: name substring. bio: bio substring. country: ISO-3166-alpha-2 codes. gender: gender labels. occupation: free-text occupation substrings. role_in: canonical role keys (founder, product_leader, engineer, …) that OR-expand into many occupation substrings, and merge with any explicit occupation. Pass an unknown key to see the full list in the [validation_error]. age_min / age_max: inclusive age bounds. education_level_in, household_in, locale_type_in, income_level_in, employment_status_in: extended demographic enums, snake_case; the legal values are in docs_get("concepts/person"). requires_captions, uses_screen_reader, prefers_reduced_motion, prefers_high_contrast, has_any_accessibility_need: bool filters over the accessibility_profile JSONB. include_bio, include_accessibility_profile: default False (each is large per row; fetch a single Person for the full payload). include_evidence: single mode only - attaches persisted EvidenceTrace rows (newest-first) under the Person’s evidence; rejected in list mode, where per-row evidence would blow the token budget. Within a dimension (country / gender / occupation / each *_in enum) values OR; across dimensions they AND. See docs_get("concepts/people") for people-selection semantics. List mode (no person_id): this workspace’s own people by default - the same pool a bare people={sample: N} draws from, so what you list here is what a run can draw. Widen with scope. Returns a PaginatedList[Person] ({items, total, returned, limit, offset, has_more}); total is the match count, handy for pre-flighting a pair-mode side’s pool (the *_in enums + a11y booleans share their vocabulary with RoleCriteria). If nothing matches, fall through to person_generate to mint matching people. Public-pool rows surface but can’t be deleted by the caller (person_delete → [auth_failed]). Single mode (with person_id): that Person with workspace-scoped custom fields + usage stats. Three text-search dimensions (each case-insensitive substring, AND’d): search → name; bio → narrative bio; occupation=[...] → occupation (OR’d within the dimension). role_in is a best-effort convenience over free-text occupation, not an indexed taxonomy. scope="all" orders every pool private → platform → published. Two vocabularies meet here. This FILTER takes workspace / shared / platform (plus the aliases private / public); a returned Person.visibility reads private / published / platform. private is workspace-only, published community-visible, platform admin-curated. So person_attach needs a Person whose visibility is private; filter for that pool with visibility="private". Extended demographic enums (snake_case, must match spec/profile-enums.v1.json):

• education_level_in: less_than_secondary, secondary, some_post_secondary, vocational_or_associate, bachelor, graduate.
• household_in: single, couple_no_kids, couple_with_kids, single_parent, shared_housing, adult_with_parents, multi_generational.
• locale_type_in: urban, suburban, small_town, rural.
• income_level_in: lower, lower_middle, middle, upper_middle, upper, prefer_not_to_say.
• employment_status_in: employed_full_time, employed_part_time, self_employed, unemployed_seeking, student, homemaker, retired, unable_to_work, other.

Accessibility booleans (filter over the accessibility_profile JSONB): requires_captions, uses_screen_reader, prefers_reduced_motion, prefers_high_contrast, has_any_accessibility_need. Returns PaginatedList[Person] without person_id, or one Person with it. Full shape: docs_get("reference/responses").

​

Parameters

​

source_upload

Tier: write · Tags: person, write Upload one piece of real evidence (email, PDF, text/doc, image, audio) so a later person_generate can ground a participant “ish” in how a real person reacted. Returns a source_upload_id to hand to person_generate(source_upload_ids=[...]). See docs_get("concepts/source"). Pass the bytes with inline_base64 (or a data: URL) - that is the portable path and the only one that works against the hosted MCP server, which cannot see your filesystem. source_path reads a LOCAL file from the MCP server’s own filesystem, so it only helps when you run the server yourself; an http(s):// URL is fetched server-side. workspace_id: UUID or short alias (e.g. w-6ec) of the workspace. source_path: read the evidence from the MCP server’s filesystem (a local path only works when the server runs on your machine), an http(s):// URL (fetched server-side, SSRF-guarded, 10MB cap), or a data: URL. Supported MIME: audio/*, image/*, text/*, application/pdf, application/json, office-document types. Omit when passing inline_base64. reaction: researcher note on how the real person reacted to THIS artifact (e.g. “called this proposal lazy and low-effort”); rides along to the agent. Backend caps it at 500 chars. inline_base64: raw base64-encoded file bytes (no data: prefix) - the portable input for hosted MCP clients that can pass the bytes but not a server-visible path. file_name is REQUIRED with this (it carries no name or MIME). Mutually exclusive with a non-data source_path. file_name: name to record for the upload; required with raw inline_base64, optional otherwise (overrides the path/URL basename). content_type: MIME override; inferred from file_name / the remote Content-Type when omitted. Returns SourceUploadResponse discriminated by ok; on success source_upload_id is the new source’s ID. Full shape: docs_get("reference/responses").

​

Parameters