MCP Tool Reference

The core tools registered by the OpenTrain MCP server, grouped by surface. The sixteen opentrain_job_instructions_* tools for canonical Instructions, twelve base Project To-do and quiz tools, 29 hosted/stdio selective-coaching tools, the stdio-only coaching image uploader, individualized LMS retraining tools, Shared Job Context tools, and job-quality tools are documented on their dedicated pages. Each tool’s scope, feature flag, and claim requirements mirror the endpoint it wraps — the linked endpoint page has the full request/response shapes and error tables.

Every tool returns a human-readable text summary plus the exact API response in structuredContent; failures return isError: true with the HTTP status and the error envelope. Scopes and feature flags are explained in Scopes and Capabilities.

Group	Tools
Auth and identity	register_agent, claim_account, claim_status, auth_status, capabilities
Jobs	create_job_draft, update_job_draft_fields, publish_job, update_published_job, close_job, list_jobs, search_jobs
Proposals and candidates	list_proposals, get_proposal, get_freelancer_profile, invite_freelancer, hire_proposal
Messages	read_messages, send_message, send_managed_job_message, start_proposal_conversation
Contracts and milestones	list_contracts, get_contract, create_milestone, request_milestone_funding, request_milestone_approval, get_approval, end_contract
Credits	get_credits, list_credit_ledger, create_credit_top_up, get_credit_top_up
Updates	poll_updates
Webhooks	create_webhook, list_webhooks, get_webhook, delete_webhook
Tokens	list_tokens, revoke_token
Team	get_team, invite_team_member
Payments	list_pending_payments
Job Instructions	Sixteen canonical content tools plus 12 hosted visual-proof tools for real employer/designated-worker PNG, ARIA, diagnostics, artifacts, and review links
Project To-dos and quizzes	Twelve base tools, 29 selective-coaching tools, one stdio image-upload convenience, and 12 hosted Native Forms visual-proof tools
LMS and retraining	Course publishing plus safe active-assignment rollout, capability discovery, exact-one retraining cases, hosted worker-shaped visual proof, observe-only review links, assignment, live review, and closeout
Shared Job Context	Context, automatic synchronization, bounded polling, priorities, claims, intents, proposals, overlays, policies, the Agent Guide and Playbook, guarded managed messages, checkpoints, and handoffs
Reviewer Feedback and Task Checklists	Twelve employer-private feedback tools plus thirteen adaptive checklist authoring, preview, version, settings, and submission tools

All tool names below carry the opentrain_ prefix.

Auth and Identity

opentrain_register_agent

Register a brand-new anonymous OpenTrain agent account — no prior credentials needed. The new ot_pat_ token and claim token are saved to the shared config file, so every other tool works immediately afterwards. Refuses to overwrite existing saved credentials unless force is set. Next step: ask the human for their email and call opentrain_claim_account.

Parameter	Type	Description
agentName	string, optional	Display name for the agent identity (e.g. “Claude Code”)
organizationName	string, optional	Name for the employer organization created with the account
force	boolean, optional	Overwrite existing saved credentials with a brand-new account

Requires: nothing — anonymous and tokenless. Wraps: POST /api/agent/identity

opentrain_claim_account

Send the human owner a claim invite for the agent-registered account — the start of the claim ceremony. OpenTrain emails them a verification link; once they accept, they own the account and can add billing. Follow up with opentrain_claim_status.

Parameter	Type	Description
email	string, required	The human owner’s email address
claimToken	string, optional	Claim token from registration; defaults to the saved one

Requires: a valid, unexpired claim token (~24h window from registration). Wraps: POST /api/agent/identity/claim

opentrain_claim_status

Check whether the human has completed the claim. When the claim completes, the stored API token is upgraded to the claimed account automatically. A slow_down status means you are polling too fast — respect the poll interval from opentrain_claim_account.

Parameter	Type	Description
claimToken	string, optional	Claim token to check; defaults to the saved one

Requires: a valid claim token with an active claim attempt. Wraps: POST /api/agent/oauth/token

opentrain_auth_status

Confirm that the configured token can authenticate, and see the account’s user id, account type, claim state, and granted scopes. No parameters.

Requires: any valid token. Wraps: GET /auth/me

opentrain_capabilities

Discover the canonical root capability map for the configured token or session. The agentSurfaces block reports every operation family as disabled, rollout_gated, unauthorized, or available, plus required and granted scopes and each operation’s authorized value. Call this before a multi-step workflow, then call the family’s scoped capability tool—for LMS, opentrain_lms_capabilities. No parameters.

Requires: any valid token or authenticated session; the root discovery operation is not gated by the job-drafting feature. Wraps: GET /capabilities

Jobs

opentrain_create_job_draft

Create an unpublished job draft from a full job description or supported import payload — the primary drafting workflow. OpenTrain parses the description into structured job fields server-side; the response’s validation state lists each missing field with an ask: question to relay to the human, its type, allowed enum values, and the set: field names for opentrain_update_job_draft_fields.

Parameter	Type	Description
jobDescription	string, optional	Full plain-text job description or project brief (primary workflow)
title	string, optional	Title to prepend for plain-text imports
externalId	string, optional	Source-system id for audit/idempotency
idempotencyKey	string, optional	Reuse the same key to avoid duplicate drafts on retry
canonicalJob	object, optional	OpenTrain canonical job object (format=opentrain_canonical)
importPayload	object, optional	Supported import payload, e.g. schema.org JSON-LD

Requires: jobs:write + the public_api_job_drafting feature. Wraps: POST /job-drafts

opentrain_update_job_draft_fields

Fill in or correct fields on an existing unpublished draft. Ask the human each missing field’s ask: question, then patch the answers using the set: field names — never ask the human to author raw JSON. This tool never publishes; use opentrain_publish_job.

Parameter	Type	Description
jobId	string, required	Existing unpublished draft job id
patch	object, required	Field patch keyed by OpenTrain field names, e.g. {"experienceLevel": "INTERMEDIATE", "pricePerHour": 12}

Requires: jobs:write + the public_api_job_drafting feature. Wraps: PATCH /job-drafts/{jobId}

opentrain_publish_job

Publish a draft live on the marketplace. Runs the same validation and moderation pipeline as the in-app publish flow and is subject to per-account daily publish limits. Returns the live job URL.

Parameter	Type	Description
jobId	string, required	Unpublished draft job id to publish

Requires: jobs:write + the public_api_job_publishing feature. Wraps: POST /jobs/{id}/publish

opentrain_update_published_job

Update fields on a live published (OPEN) job. The revised listing is re-checked by moderation inline; if blocked, the job is automatically unpublished back to draft and the response explains what to fix. For unpublished drafts use opentrain_update_job_draft_fields instead.

Parameter	Type	Description
jobId	string, required	Published (OPEN) job id
patch	object, required	Field patch, same shape as opentrain_update_job_draft_fields

Requires: jobs:write + the public_api_job_publishing feature. Wraps: PATCH /jobs/{id}

opentrain_close_job

Close (archive) a published job so it stops accepting proposals and leaves public listings. Existing contracts are unaffected. Idempotent — closing an already-archived job reports alreadyClosed.

Parameter	Type	Description
jobId	string, required	Published job id to close

Requires: jobs:write + the public_api_job_publishing feature. Wraps: POST /jobs/{id}/close

opentrain_list_jobs

List the account’s own jobs (all statuses, newest first) with pagination.

Parameter	Type	Description
status	string, optional	Filter: DRAFT, OPEN, ONGOING, COMPLETED, ARCHIVED, or PENDING_APPROVAL
cursor	string, optional	Pagination cursor
limit	number, optional	Max jobs to return, 1–100 (default 25)

Requires: jobs:read. Wraps: GET /jobs/mine

opentrain_search_jobs

Search the public OpenTrain job marketplace — useful for calibrating rates and seeing how similar work is scoped before posting.

Parameter	Type	Description
q	string, optional	Free-text search query
category	string, optional	Category filter
language	string, optional	Language filter
country	string, optional	ISO country code
payType	string, optional	Payment type filter
limit	number, optional	Max results, 1–50
cursor	string, optional	Pagination cursor

Requires: nothing — tokenless public read (120 requests/minute per IP). Wraps: GET /jobs

Proposals and Candidates

opentrain_list_proposals

List proposals/candidates for a job with statuses, bids, AI interview scores, and resume match scores — the primary tool for reviewing and ranking who to hire. Use opentrain_get_proposal for one candidate in depth.

Parameter	Type	Description
jobId	string, required	Job id to list proposals for
status	string, optional	Filter such as UNREVIEWED, SHORTLISTED, HIRED, or DECLINED
cursor	string, optional	Pagination cursor
limit	number, optional	Max proposals, 1–100 (default 25)

Requires: proposals:read; the job must be yours. Wraps: GET /jobs/{id}/proposals

opentrain_get_proposal

Read a full proposal/candidate evaluation: status, bid, masked candidate, AI-interview score and summary, location/identity verification, labeling assessment, and contract state.

Parameter	Type	Description
proposalId	string, required	Proposal id to read
includeInterview	boolean, optional	Also fetch the sanitized AI-interview transcript

Requires: proposals:read; the proposal must be on a job you own. Wraps: GET /proposals/{proposalId} (+ GET /proposals/{proposalId}/interview when includeInterview is true)

opentrain_get_freelancer_profile

Read a masked AI trainer profile for candidate evaluation: title, bio, skills, stats (earned, billed hours, job success), work and labeling experience, education, reviews, and languages. Names are masked to first name + last initial pre-hire, and personal contact details are never returned — see Privacy and Work Email.

Parameter	Type	Description
idOrSlug	string, required	AI trainer user id or public profile slug

Requires: proposals:read. Wraps: GET /freelancers/{idOrSlug}

opentrain_invite_freelancer

Invite an AI trainer to a published job, creating a proposal they can respond to. Idempotent: re-inviting the same person returns the existing proposal with alreadyInvited: true.

Parameter	Type	Description
jobId	string, required	Published job id
freelancerId	string, required	AI trainer user id to invite

Requires: proposals:write + the public_api_hiring feature + a claimed account. Wraps: POST /jobs/{id}/invites

opentrain_hire_proposal

Request a hire from a proposal. Never hires anyone or moves money — records a pending approval (type: "proposal_hire") and returns 202 with an approvalUrl a signed-in human must confirm in the OpenTrain app. On confirm, OpenTrain creates the contract and funds the first escrow milestone (the human picks card or credits). A 409 with details.reason: "payment_method_required" includes a billingUrl; not_fit_confirmation_required means retry with confirmNotFitOverride: true if intentional; already_accepted means the proposal was already hired. Re-requesting with the same terms returns the same pending approval.

Parameter	Type	Description
proposalId	string, required	Proposal id to hire from
milestone	object, required	First escrow milestone: {name?, description?, amount (USD, required), dueDate?}
confirmNotFitOverride	boolean, optional	Confirm hiring a proposal previously marked “Not a fit”

Requires: proposals:write + the public_api_hiring feature + a claimed account + a payment method or covering credit balance. Wraps: POST /proposals/{proposalId}/hire

Messages

opentrain_read_messages

Read authorized conversation summaries or messages. Omit conversationId to list summaries; provide it to read messages. Never creates conversations or sends messages.

Parameter	Type	Description
conversationId	string, optional	Conversation to read; omit to list summaries
cursor	string, optional	Pagination cursor
limit	number, optional	Max records, 1–100
direction	older | newer, optional	Message pagination direction (with conversationId)
filter	all | job | proposal, optional	Summary filter (without conversationId)
unreadOnly	boolean, optional	Only conversations with unread messages (without conversationId)

Requires: messages:read; you only see conversations you participate in. Wraps: GET /messages

opentrain_send_message

Send a plain-text message into an existing conversation the token owner participates in. Runs the same membership, rate-limit, and content-policy checks as the in-app messaging flow. This tool never creates conversations — they come from proposals, invites, and hires. It is intentionally generic and unsynchronized; do not use it for claimed Shared Job Context work.

Parameter	Type	Description
conversationId	string, required	Existing conversation id
content	string, required	Plain-text message (max 10,000 chars)

Requires: messages:write + the public_api_messaging_writes feature + a claimed account. Wraps: POST /messages

opentrain_send_managed_job_message

Send a reviewed message as part of claimed live-job work. OpenTrain resolves the authorized Job Message or Proposal Message to its canonical job and commits the message plus shared-context advance atomically.

Parameter	Type	Description
conversationId or contractId	string, exactly one	Existing authorized conversation, or the active contract whose Job Message conversation OpenTrain resolves server-side
content	string, required	Plain-text reviewed message (max 10,000 characters)
idempotencyKey	string, required	Stable 8–128-character key using letters, numbers, ., _, :, or -
jobOperationsGuard	object, required	Exact job/context/action revisions, signed claim receipt, and latest observed message ID; use null only for an observed-empty conversation

The tool fails before network access when the input is incomplete. A teammate or AI trainer reply, context change, action transition, expired claim, or wrong job binding fails stale before message or notification creation.

Requires: messages:write + messages:manage, a claimed account, and canonical job/conversation access. Wraps: POST /messaging/management/messaging_management.messages.send. See MCP: Shared Job Context.

opentrain_start_proposal_conversation

Start (or fetch) the pre-hire direct-message thread for a proposal so you can message the candidate before hiring. Idempotent get-or-create; returns the conversationId to use with opentrain_send_message. Employer side only.

Parameter	Type	Description
proposalId	string, required	Proposal to open the pre-hire thread for

Requires: messages:write + the public_api_messaging_writes feature + a claimed account. Wraps: POST /proposals/{proposalId}/conversation

Contracts and Milestones

opentrain_list_contracts

List contracts (hired AI trainers), each with milestones, the post-hire job DM conversationId, and the masked freelancer identity (first name + last initial).

Parameter	Type	Description
jobId	string, optional	Filter to one job
status	active | ended, optional	Status filter; omit for both

Requires: payments:read. Wraps: GET /contracts

opentrain_get_contract

Read one contract in detail: status, milestones with funding/approval state, AI trainer identity, the post-hire job DM conversationId, and the budget snapshot (funded vs consumed, state OK/LOW/DEPLETED).

Parameter	Type	Description
contractId	string, required	Contract id to read

Requires: payments:read. Wraps: GET /contracts/{contractId}

opentrain_create_milestone

Create a new unfunded milestone on an existing contract. No money moves at creation — use opentrain_request_milestone_funding afterwards.

Parameter	Type	Description
contractId	string, required	Contract to add the milestone to
description	string, required	Description of the work to be delivered
name	string, optional	Short milestone name
amountUsd	number, optional	Milestone amount in USD
volume	number, optional	Unit volume (e.g. label count) for per-unit milestones
dueDate	string, optional	Due date (ISO 8601)

Requires: payments:write + the public_api_payments_write feature + a claimed account. Wraps: POST /contracts/{contractId}/milestones

opentrain_create_admin_balance_milestone

Create and internally fund a later milestone through OpenTrain’s restricted platform-admin workflow. For hourly and per-label contracts, supply volume or omit it so the server derives the value from amountUsd and the canonical contract rate.

Parameter	Type	Description
contractId	string, required	Contract that will own the milestone
idempotencyKey	string, required	Stable request key; reuse it only for an identical retry
description	string, required	Work covered by the milestone
amountUsd	number, required	Positive milestone amount
volume	number, optional	Positive hours or labels; may be derived for a volume-based contract
name	string, optional	Short milestone name
dueDate	string, optional	ISO 8601 due date

This tool is unavailable to ordinary employers. The server independently verifies every restricted platform-admin condition; the scope alone is insufficient. Creation moves $0 and creates no Stripe charge or PaymentIntent. Releasing payment remains a separate human-authorized action.

Requires: admin_balance_hire:create, the default-off admin-balance agent surface, a claimed account, and all server-verified platform-admin gates. Wraps: POST /contracts/{contractId}/admin-balance-milestones

opentrain_fund_admin_balance_milestone

Apply ADMIN_BALANCE to one existing eligible NOT_FUNDED milestone without creating a duplicate.

Parameter	Type	Description
contractId	string, required	Contract that must own the milestone
milestoneId	string, required	Existing NOT_FUNDED milestone
idempotencyKey	string, required	Stable request key; identical retries converge on the same result

The server verifies linkage, compensation consistency, state, sequencing, payment holds, and all restricted platform-admin conditions. Success transitions the existing milestone to ACTIVE_FUNDED, moves $0, and creates no Stripe charge or PaymentIntent. Releasing payment still requires a separate human approval.

Requires: the same restricted authorization as opentrain_create_admin_balance_milestone. Wraps: POST /contracts/{contractId}/admin-balance-milestones/{milestoneId}/fund

opentrain_request_milestone_funding

Request escrow funding for a milestone. This does not move money: it returns a pending approval with an approvalUrl that a signed-in human must open and confirm (expires in ~72h) — the co-sign pattern. Watch opentrain_poll_updates for approval.confirmed, or re-check with opentrain_get_approval.

Parameter	Type	Description
milestoneId	string, required	Milestone to fund

Requires: payments:write + the public_api_payments_write feature + a claimed account + a payment method on file. Wraps: POST /milestones/{milestoneId}/fund

opentrain_request_milestone_approval

Request approval (payment release) of a funded milestone. Like funding, this only creates a pending human approval with an approvalUrl (~72h expiry) — no money moves until the human confirms.

Parameter	Type	Description
milestoneId	string, required	Funded (ACTIVE_FUNDED) milestone to release

Requires: payments:write + the public_api_payments_write feature + a claimed account. Wraps: POST /milestones/{milestoneId}/approve

opentrain_get_approval

Check the status of a pending human co-sign approval (milestone funding, release, or contract end): pending, confirmed, declined, or expired, plus the execution result once confirmed.

Parameter	Type	Description
approvalId	string, required	Approval id from a fund/approve/end request

Requires: payments:read. Wraps: GET /approvals/{approvalId}

opentrain_end_contract

End a contract. With no funded milestones it ends immediately; if funded escrow is at stake, the call instead returns a pending approval with an approvalUrl a human must confirm — no funds move until then.

Parameter	Type	Description
contractId	string, required	Contract to end

Requires: payments:write + the public_api_payments_write feature + a claimed account. Wraps: POST /contracts/{contractId}/end

Credits

opentrain_get_credits

Read the prepaid credit balance: available, reserved (escrow holds), and total. No parameters.

Requires: payments:read + the public_api_credits feature. Wraps: GET /credits

opentrain_list_credit_ledger

Page through the credit ledger — top-ups, escrow holds, hold releases, captures, refunds, and adjustments, newest first. Each entry links the related top-up, proposal, contract, or milestone ids.

Parameter	Type	Description
cursor	string, optional	nextCursor from a previous page
limit	number, optional	Page size, 1–100 (default 50)

Requires: payments:read + the public_api_credits feature. Wraps: GET /credits/ledger

opentrain_create_credit_top_up

Start a credit top-up. No money moves from this call: it returns a Stripe Checkout checkoutUrl that a signed-in human must open and pay (expires in ~24h). Once paid, the balance updates automatically.

Parameter	Type	Description
amountUsd	number, required	Top-up amount in USD (min $10, max $10,000)

Requires: payments:write + the public_api_credits feature + a claimed account. Wraps: POST /credits/top-ups

opentrain_get_credit_top_up

Check a top-up’s status: pending (awaiting human payment), completed (credits added), canceled, or expired.

Parameter	Type	Description
topUpId	string, required	Top-up id from opentrain_create_credit_top_up

Requires: payments:read + the public_api_credits feature. Wraps: GET /credits/top-ups/{topUpId}

Updates

opentrain_poll_updates

Poll the delta feed of account events (new proposals, proposal status changes, new messages, contracts, milestone changes, pending payments, confirmed approvals, budget state changes) in one cheap call instead of re-reading every resource. Payloads carry IDs only — fetch details with the matching read tool. Event visibility follows the token’s scopes.

Parameter	Type	Description
cursor	string, optional	nextCursor from the previous poll; omit on the first poll
limit	number, optional	Max events, 1–200 (default 50)

Requires: at least one of proposals:read, messages:read, payments:read. Wraps: GET /updates

Webhooks

opentrain_create_webhook

Subscribe an HTTPS URL to platform events (push instead of polling). Deliveries are signed with HMAC-SHA256 — see Verify Webhook Signatures. The signing secret is returned once in this response; store it immediately. The subscription only receives events created after it.

Parameter	Type	Description
url	string, required	HTTPS endpoint that will receive signed deliveries
eventTypes	string[], required	Event types to subscribe to, e.g. ["proposal.received", "message.received"]

Requires: webhooks:manage + the public_api_webhooks feature + the matching read scope for each subscribed event type. Wraps: POST /webhooks

opentrain_list_webhooks

List all webhook subscriptions with URL, event types, and status. Signing secrets are never included. No parameters.

Requires: webhooks:manage + the public_api_webhooks feature. Wraps: GET /webhooks

opentrain_get_webhook

Read one webhook subscription: URL, event types, status (ACTIVE or DISABLED), and failure/disable details. The signing secret is never returned — if lost, delete and re-create the subscription.

Parameter	Type	Description
webhookId	string, required	Webhook subscription id

Requires: webhooks:manage + the public_api_webhooks feature. Wraps: GET /webhooks/{webhookId}

opentrain_delete_webhook

Delete a webhook subscription and stop its deliveries. This is also how a DISABLED subscription is resumed: delete it and create a new one (which mints a new secret).

Parameter	Type	Description
webhookId	string, required	Webhook subscription id to delete

Requires: webhooks:manage + the public_api_webhooks feature. Wraps: DELETE /webhooks/{webhookId}

Tokens

opentrain_list_tokens

List the account’s API tokens with masked previews, scopes, status, and last-used timestamps — secrets are never shown. No parameters.

Requires: any valid token — token management needs no specific scope or feature flag. Wraps: GET /tokens

opentrain_revoke_token

Revoke an API token by id. Irreversible — the token stops working immediately.

Warning

Revoking the token the MCP server itself is using breaks every subsequent call. Mint a replacement over HTTP with POST /tokens and switch to it first.

Parameter	Type	Description
tokenId	string, required	Id of the token to revoke

Requires: any valid token — token management needs no specific scope or feature flag. Wraps: DELETE /tokens/{tokenId}

Team

opentrain_get_team

Read the employer team: organization, members with roles, and pending email invites. No parameters.

Requires: team:read + the public_api_team feature. Wraps: GET /team

opentrain_invite_team_member

Invite a human to the employer team by email, giving them shared access to jobs and the team inbox once they accept. Inviting an existing member returns already_member; users with existing accounts are added directly (member_added).

Parameter	Type	Description
email	string, required	Email of the human to invite

Requires: team:write + the public_api_team feature + a claimed account. Wraps: POST /team/invites

Payments

opentrain_list_pending_payments

List pending payments on the account — read-only; never releases funds. No parameters.

Requires: payments:read. Wraps: GET /payments/pending