Ttctl

List the scheduled break windows for a specific engagement. A break is a planned period when the talent will not be working on the engagement (vacation, time off, etc.). The id parameter is the engagement id (TalentJobActivityItem id), the same id used by `ttctl_engagements_show`. Example user prompts: - "Show me the scheduled breaks on engagement act_xyz." - "Do I have any vacations planned on my current Toptal engagement?"

List the server-side catalog of valid break-reason identifiers for `ttctl_engagements_breaks_add` (the `reasonIdentifier` argument). Reads `platformConfiguration.engagementBreakReasons` from the mobile gateway. Returns an array of `{identifier, nameForRole}` sorted by `identifier`. `identifier` is what the user supplies to `ttctl_engagements_breaks_add`; `nameForRole` is the human-readable label. Use this tool to discover valid `reasonIdentifier` values before scheduling a break — the catalog can change over time. Example user prompts: - "What break reasons can I use when scheduling a Top…

Cancel a previously-scheduled break by its id (the id returned by `ttctl_engagements_breaks_list`). **This is a write operation**: it cancels a scheduled break on the live Toptal Talent platform. Confirm with the user before invoking. Example user prompts: - "Cancel break br_abc on engagement act_xyz." - "Remove the scheduled break starting June 1 on my Toptal engagement."

Move an existing scheduled break to a new date window in-place, without removing and re-adding it. Preserves the existing break's reason and comment (the wire mutation only carries the new startDate + endDate). Required: `breakId` (the engagementBreak id, from `engagements_breaks_list`), `startDate` (YYYY-MM-DD), `endDate` (YYYY-MM-DD). **This is a write operation**: it changes a scheduled break's dates on the live Toptal Talent platform. Confirm with the user before invoking. Example user prompts: - "Reschedule break br_abc to July 1 through July 8." - "Move my scheduled vacation from …

List the signed-in user's Toptal Talent engagements (active by default). An engagement is an active assignment between the user and a client (= what users colloquially call 'current job' or 'current contract'). Filter via `status`: - `active` (default): currently active engagements - `past`: closed engagements - `all`: both Optional `keywords` is a free-text filter (AND across multiple). Pagination (#375): pass `page` (1-indexed) / `perPage` to walk beyond the default first slice. Returns `{ items, pageInfo }` where `pageInfo` is `{ currentPage, perPage, totalPages, hasNextPage }` — i…

List the payments under an engagement on the Toptal Talent platform — invoices/payouts with amount, status, due/paid dates, and billing cycle. **Input is the JOB id** (the `job.id` from `ttctl_engagements_list` or `ttctl_jobs_list`), NOT the activity-item row id the other engagements tools take — the wire op `GetEngagementPayments` is keyed by `$jobId`. Pagination (ADR-007 row 4, limit + forward cursor): `limit` caps the page; `after` is a forward cursor that IS a payment id. Returns `{ items, totalCount, nextCursor }` — pass `nextCursor` back as `after` to walk forward; a null `nextCursor` …

Fetch a single engagement's full detail by id (the row id from `ttctl_engagements_list`, which is the underlying TalentJobActivityItem id). Returns the engagement metadata (status, start/end dates, expected hours, commitment), the underlying job (title, client, description, work type), the current agreement (rates, commitment), earnings summary, any scheduled breaks, the client-side hiring-manager contacts (`job.contacts`), and the Toptal-side recruiter points-of-contact (`job.pointsOfContact.current` / `.handoff`). Example user prompts: - "Show me the details of engagement act_xyz." - "W…

Aggregate engagement counts: returns per-status totals (active, past) plus the overall sum. Issues 2 server calls in parallel (one per engagement-bearing status group). Each count is server-provided (totalCount on JobActivityList) — no client-side aggregation. Example user prompts: - "How many Toptal engagements have I had in total?" - "Show me a breakdown of my Toptal engagements by status." Dry-run note: returns `{ ok: true, dryRun: true, previews: [...] }` (plural `previews`) — one `JobActivityItems` preview per engagement status group (2 total: ACTIVE_ENGAGEMENT, CLOSED_ENGAGEMENT),…

Accept (confirm) a Toptal Interest Request — the wire mutation `ConfirmAvailabilityRequest` (mobile-gateway). Mirror of the "View Job Interest Request → Respond" button on the Toptal portal. **DESTRUCTIVE** — accepting an IR transitions the AvailabilityRequest from PENDING to CONFIRMED, creating a `JobApplication` for the underlying job. There is no withdraw operation on the wire. Always preview with `dryRun: true` first if uncertain. **Input id**: the `availabilityRequestId` from `ttctl_interest_requests_list` rows (NOT the `id` field, which is the activity-item id used by `_show`). Both id…

List the signed-in user's pending Toptal Interest Requests — the UI label for recruiter-initiated availability checks ("respond" / "decline" decision flow). On the wire these are activity-list rows in the `ON_RECRUITER_REVIEW` status group; this tool wraps `ttctl_applications_list --statusGroups ON_RECRUITER_REVIEW` and projects each row into a trimmed triage shape: id, statusVerbose, jobTitle, clientName, jobUrl, lastUpdatedAt, daysPending, fixedRate, recruiter. `recruiter` (#539) carries `firstName` / `lastName` / `fullName` lifted from the embedded `availabilityRequest.recruiter` sub-sele…

Reject (decline) a Toptal Interest Request — the wire mutation `RejectAvailabilityRequest` (mobile-gateway). Mirror of the "View Job Interest Request → Decline" form on the Toptal portal. **DESTRUCTIVE** — rejecting an IR transitions the AvailabilityRequest to REJECTED (terminal, archived). No undo. Always preview with `dryRun: true` first if uncertain. **Input id**: the `availabilityRequestId` from `ttctl_interest_requests_list` rows (NOT the `id` field, which is the activity-item id used by `_show`). **Fields**: - `id` (required): AvailabilityRequest id. - `reason` (required): one of …

List the Interest Request decline-reason inventory — the `key` / `value` / `isMandatory` rows the portal's Decline form uses. Pass one of the surfaced `key` values to `ttctl_interest_requests_reject`. Returns `{ fixed: [...], flexible: [...] }` — the portal renders only the slice matching the AR's `kind`, so clients should likewise pick the slice that matches the AR being declined. Read-only, idempotent. Server-localised (the `value` text matches the session's locale). Example user prompts: - "What reasons can I decline Interest Requests with?" - "Show me the reject-reason inventory for…

Submit a direct application to a Toptal job — the wire mutation `JobApply` (mobile-gateway). Mirror of the Toptal portal's apply screen submit action. **DESTRUCTIVE** — applying creates a new `JobApplication` row on the user's Toptal activity and notifies the recruiter. There is no withdraw operation on the wire. Always preview with `dryRun: true` first if uncertain. **Consent gate (legal compliance)**: `consentIssued` MUST be the literal `true` — represents the talent's acceptance of Toptal's apply terms (the consent affirmation rendered on the apply screen). Auto-filling this on the talent…

Fetch the pre-apply data the Toptal portal renders on the apply screen for a given job: position summary, recruiter-pinned rate, suggested rate (defaults to the talent's configured rate), currency, application status, and a `canApply` flag. Read-only — does not mutate any server state. Use this together with `ttctl_jobs_apply_questions` and `ttctl_jobs_apply_rate_insight` to compose the context an LLM agent needs before authoring an application via `ttctl_jobs_apply`. Example user prompts: - "What's the apply context for Toptal job <id>?" - "What rate is suggested for job <id>?"

Fetch the matcher-questions and expertise-questions a job's apply form requires the talent to answer. Returns `{ matcherQuestions: [...], expertiseQuestions: [...] }`. Each entry carries `identifier`, `prompt` (the question text), `type` (`matcher` | `expertise`), `isMandatory`, plus the choice metadata: `options` (the dropdown's allowed values — an empty array for free-text questions), `suggestedAnswer` (the recruiter-preselected value, or null), and `inputType` (`dropdown` when `options` is non-empty, else `free-text`). For a dropdown matcher question, answer with one of `options` (or the `s…

Fetch the rate-competitiveness insight the Toptal portal renders alongside the apply screen's rate input. Returns either a `competitive` variant (talent's rate is in range; carries a `recommendedRate`) or an `uncompetitive` variant (talent's rate is above the platform's expected band for this job). Read-only — does not mutate any server state. Pair this with `ttctl_jobs_apply_data` (which supplies the suggested rate) to compose the rate-decision context an LLM agent needs before invoking `ttctl_jobs_apply`. Returns `null` when the platform does not surface an insight for this job. Example u…

Fetch the talent's own historical answers to questions semantically similar to those on a given job's apply form — advisory autocomplete suggestions an LLM agent can offer the user when authoring `matcherAnswers` / `expertiseAnswers` for `ttctl_jobs_apply`. Read-only — does not mutate any server state. **Off the critical apply path**: this tool is intentionally a SEPARATE read step from `ttctl_jobs_apply_data` / `ttctl_jobs_apply_questions` / `ttctl_jobs_apply_rate_insight`. The underlying wire query (`SimilarJobQuestionAnswers`) is heavier (server-side semantic-similarity computation) and m…

Clear interest flags (both `saved` and `not-interested`) on a job. Use this to undo a previous `not-interested` mark, or to remove a job from saved.

Fetch the signed-in talent's dashboard 'my activity' list — every job they have an engagement, application, or pending action on (`viewer.jobActivityList`), distinct from `ttctl_jobs_list` / `ttctl_jobs_recommended` (browse feeds). Each row carries the job (same shape as `ttctl_jobs_list`) plus activity status (`status`, `statusGroup`, `statusColor`, `lastUpdatedAt`) and `engagement` / `application` presence markers, with offset-style `pageInfo`. Pagination: - `page`: 1-indexed page number (≥ 1). Default: 1. - `perPage`: items per page (≥ 1; server-capped). Default: 20. Example user prom…

Count the talent's dashboard job-activity items in ONE status group. The wire op requires a status group, so `statusGroup` is REQUIRED — this is not an input-less count. Known groups: `ACTIVE_ENGAGEMENT`, `CLOSED_ENGAGEMENT`, `ON_CLIENT_REVIEW`, `ON_RECRUITER_REVIEW`. Returns `{ statusGroup, count }`. Example user prompts: - "How many active engagements do I have?" - "Count my jobs awaiting recruiter review."

Browse the user's current eligible job opportunities on Toptal Talent. Returns one page of eligible jobs plus offset-style `pageInfo` (`currentPage`, `perPage`, `totalPages`, `hasNextPage`) so callers can iterate beyond the default first page (≤20). **What 'eligible' means**: jobs the signed-in user can apply to right now. The wire's `eligibleJobs` query pre-excludes jobs that are already-applied, position-fulfilled, marked `not-interested`, or apply-blocked for the user (skill / specialization mismatch, missing ID verification, insufficient available hours, legacy-client restriction, etc. — …

Mark a Toptal job as viewed. The web UI normally auto-marks on detail-page open — this tool exposes the mutation for completeness.

Fetch the platform's per-criterion match-quality assessment for a job — Toptal's view of how well the signed-in talent matches the job (the portal's job-match panel). Returns `{ metrics: [...] }`; each metric carries `name`, `slug`, `statusV2` (the per-criterion status), `description`, `explanation`, `isRequired`, and `forAvailabilityRequest`. The wire exposes no single aggregate score — the breakdown IS the per-criterion list. Read-only — does not mutate any server state. Returns an empty `metrics` array when the platform surfaces no assessment for the job (e.g. an already-engaged job). Exa…

Mark a Toptal job as not-interested with a reason. `reason` is required (server rejects empty strings). If the job was previously saved, this mutation clears the saved flag.

List Toptal jobs the user marked as not-interested. Returns one page of dismissed jobs plus offset-style `pageInfo` (`currentPage`, `perPage`, `totalPages`, `hasNextPage`) so callers can iterate beyond the default first page (≤20). Pagination (#369): - `page`: 1-indexed page number (≥ 1). Default: 1. - `perPage`: items per page (≥ 1; server-capped). Default: 20.

Fetch the platform's per-job rate-intelligence panel for a job — Toptal's view of whether the signed-in talent's rate is competitive for it. Returns a `JobRateInsight` object whose `kind` is `competitive` or `uncompetitive`: both carry `estimatedRevenue` + `estimatedRevenueExplanation`; the competitive variant adds `longTermDisclaimer`, the uncompetitive variant adds the recommended rate band (`recommendedRate` + `recentApplicationRate`). Every rate is a verbatim BigDecimal string. Read-only — does not mutate any server state. Returns `null` when the platform surfaces no rate insight for the …

Fetch Toptal's algorithmic job-recommendation feed for the signed-in user — the 'what should I look at' view, distinct from `ttctl_jobs_list`'s filter-based browse. Returns one page of recommended jobs (same row shape as `ttctl_jobs_list`) plus offset-style `pageInfo` (`currentPage`, `perPage`, `totalPages`, `hasNextPage`). Pagination: - `page`: 1-indexed page number (≥ 1). Default: 1. - `perPage`: items per page (≥ 1; server-capped). Default: 20. Example user prompts: - "What Toptal jobs are recommended for me?" - "Show my recommended opportunities."

Mark a Toptal job as saved (bookmark). The job appears in `ttctl_jobs_saved` afterwards. If the job was previously marked not-interested, this mutation clears that flag (the wire's interest-status model is one-of-three: saved / not-interested / cleared).

List the user's saved (bookmarked) Toptal jobs. Returns one page of saved jobs plus offset-style `pageInfo` (`currentPage`, `perPage`, `totalPages`, `hasNextPage`) so callers can iterate beyond the default first page (≤20). Pagination (#369): - `page`: 1-indexed page number (≥ 1). Default: 1. - `perPage`: items per page (≥ 1; server-capped). Default: 20.

Show the user's current job-search subscription state. **Cardinality note (R2)**: the platform supports a SINGLE subscription per user — there is no list of named subscriptions. Returns `{ active: false, filters: null }` when no subscription is active, or the active subscription filters when one is.

Terminate the user's active job-search subscription. Idempotent — terminating a non-active subscription returns success.

Start a new job-search subscription with the supplied filters. If a subscription is already active, it is replaced. Returns the post-mutation subscription state.

Fetch a single job's detail view by id. Returns title, description, skills, client metadata, time-zone, rates, interest-state flags, the client-side hiring-manager contacts (`contacts`), and the Toptal-side recruiter points-of-contact (`pointsOfContact.current` / `.handoff`). Example user prompts: - "Show me Toptal job job_abc123." - "What's the description for that job I just listed?" - "Who is the client-side hiring manager on job job_abc123?"

Batch-fetch several jobs' detail views by id in a single wire round-trip — the bulk sibling of `ttctl_jobs_show`. Each job carries the same fields as `ttctl_jobs_show`. Returns the found jobs in INPUT order; ids that resolve to no job are omitted (diff the returned `id`s against the ids you passed). Accepts up to 20 ids. Example user prompts: - "Compare Toptal jobs job_abc123 and job_def456." - "Show me the details for these three jobs I saved."

Clear interest flags on a Toptal job — the wire's only 'remove saved' path. Note that this ALSO clears `not-interested` (single wire mutation covers both signals).

List Toptal jobs the user has marked as viewed. **Wire limitation (R1, #372)**: the wire has no `viewed` filter on eligibleJobs (the Toptal mobile app confirms this — its `InitialJobs` / `SavedJobs` operations expose only `notInterested` and `saved` on the filter input). This tool iterates the FULL eligibleJobs pool, applies a client-side filter on the `viewed` boolean, and dedups by job id, then slices to the requested page. Internal fetch is capped at 50 underlying pages (~1000 jobs) for safety; pathologically-large pools surface a stderr warning. Cost: O(N/20) wire calls per invocation. A…

List the signed-in user's performed actions — the per-role audit log of viewer activity (status changes, applications submitted, and similar). Pagination (ADR-007 row 5, bidirectional cursor): `before` / `after` take opaque cursor tokens echoed from a prior page; `limit` caps the page size. Omit all three for the server's default first page. Returns a bare list (no totalCount); each action carries id, category, description (template + variables), occurredAt. Example user prompts: - "What have I done recently on Toptal?" - "Show my last 10 profile actions." - "When did I last submit an …

List the talent's configured Toptal payment methods (Payoneer / wire / Toptal Payments / etc.). The preferred method is marked `preferredOption: true`. Returns `{ methods, availableMethods }` where `availableMethods` is the enum list of method types the role may add. Read-only — adding / removing / changing preferred method is out of scope for v1 (the Toptal admin flow lives in the web portal). Example user prompts: - "What payment methods are configured on my Toptal account?" - "Which is my preferred Toptal payment method?"

Fetch one payment method's detail by id. No per-id wire op exists; the tool fetches the full list and filters locally. Dry-run note: the underlying preview is for `PaymentOptions` (the list query), since the per-method filter is a client-side operation.

List the signed-in user's historical Toptal payouts. A payout is a `TalentPayment` record carrying the billing-cycle amount, status (PAID / DUE / OUTSTANDING / OVERDUE / ON_HOLD / DISPUTED), and memorandum adjustments. Optional `fromDate` / `toDate` (YYYY-MM-DD, inclusive) filter by `createdOn`. Paginated (#373): pass `page` (1-indexed, default 1) and `perPage` (default 20) to page beyond the first 20 records. The response is `{ items, summary, pageInfo }` where `pageInfo` carries `currentPage` / `perPage` / `totalPages` / `hasNextPage` — iterate by incrementing `page` while `pageInfo.hasNex…

Fetch one payout's full detail by `TalentPayment.id` (the row id from `ttctl_payments_payouts_list`). Example user prompts: - "Show payout pmt_xyz." - "What is the amount of my Toptal payout pmt_abc?"

Submit a rate-change request on the talent's Toptal account. Required: - `kind`: one of `current-engagement`, `future-engagements`, `consultation`. - `desiredRate`: target hourly rate as a decimal string (e.g. `"95.0"`). - `answers`: array of `{questionId, value, comment?}` — fetch the catalog via `ttctl_payments_rate_questions` and answer each. Conditional: - `engagementId`: REQUIRED for `kind: current-engagement`; rejected for the other two kinds (those are account-wide). Optional: - `talentComment`: free-text comment attached to the request. **This is a write o…

Show the talent's current default hourly rate via the single lightweight `GetTalentRate` query (#447). Returns the server-formatted verbose display string (e.g. "USD 95.00 hourly") plus the active `viewerRole.roleId`. Sibling to `ttctl_payments_rate_show` (unified projection with market insight + validation + change history): one query, three nested fields, no composition. Use this when the answer is just "what's my rate". Example user prompts: - "What is my current Toptal hourly rate?" - "How much do I make per hour?"

List the form questions the user must answer when submitting a rate-change request. Discovery sub-command — call this BEFORE `ttctl_payments_rate_change` to learn the required `answers[]` shape. Each question returns `{id, kind: 'RADIO'|'TEXT', label, options[]}`. `RADIO` kind: pick `value` from `options[].label`. `TEXT` kind: free-text. An option may set `commentRequired: true` — when chosen, pass an accompanying answer comment. Example user prompts: - "What questions do I need to answer for a Toptal rate change?"

Show the talent's current default hourly rate, market insight (competitiveness, recommended rate), validation rules (min rate, rate step), and the most-recent or in-flight rate-change request. Unified projection — issues 2 parallel queries (`LastRateChangeRequest` + `RateChangeFormDetails`) and composes the result. Example user prompts: - "What is my current Toptal rate?" - "Show me the status of my rate-change request." - "What is the minimum hourly rate I can request?"

Batch-fetch several payouts' full detail by `TalentPayment.id` in a single wire round-trip — the bulk sibling of `ttctl_payments_payouts_show`. Each payout carries the same fields as that tool. Returns the found payouts in INPUT order; ids that resolve to no payout are omitted (diff the returned `id`s against the ids you passed). Accepts up to 20 ids. Example user prompts: - "Compare Toptal payouts pmt_abc123 and pmt_def456." - "Show me the details for these three payouts."

Show the talent's aggregate Toptal payment totals — six server-computed sums spanning the entire payment history: `totalPaid`, `totalDue`, `totalOutstanding`, `totalOverdue`, `totalOnHold`, `totalDisputed` (each a decimal string). Lightweight at-a-glance financial overview via the single `GetTalentPaymentSummary` query. Sibling to `ttctl_payments_payouts_list`, which returns the individual payout rows (paginated) plus the same aggregate for the queried window — reach for `summary` when the answer is just the totals. Read-only — no side effects. Example user prompts: - "What are my total T…

Fetch the URLs of the signed-in user's profile photo (default / original / small variants plus the recommended crop rectangle and a `isResolutionSatisfied` flag). Pass `dryRun: true` to preview the request without firing the query. Example user prompts that should map to this tool: - "Show me my Toptal profile photo." - "What are the URLs of my profile photo variants?" - "Is my profile photo resolution OK?"

Upload a new profile photo from a local image file (jpg / png / gif / webp). Image content-type is inferred from the file extension. Pass `dryRun: true` to preview the request without firing the mutation. The preview describes the GraphQL `operations` envelope only (not the multipart binary body). Example user prompts that should map to this tool: - "Upload /Users/me/Pictures/headshot.jpg as my Toptal profile photo." - "Set my profile photo to ./avatar.png."

Fetch the signed-in user's Toptal Talent profile (identity, role, vertical, skills, hours, rate, bio, headline, languages). Returns the merged read payload from both the mobile-gateway (`profile`) and the talent-profile (`basicInfo`) surfaces. `basicInfo.bio` mirrors `Profile.about`; `basicInfo.headline` mirrors `Profile.quote`. `basicInfo` is `null` when the secondary read call fails non-fatally. Pass `verbose: true` to fetch the FULL portal `GetViewer` projection instead (legal-document acceptance, post-activation/market state, hire-me banner, pending surveys/quizzes, rate insight, and the…

Update the signed-in user's profile bio, headline, and/or twitter handle. At least one must be supplied. Pass `dryRun: true` to preview the request without firing the mutation. Example user prompts that should map to this tool: - "Update my bio to: Senior backend engineer specialising in Go and PostgreSQL." - "Change my Toptal headline to 'CTO at AcmeCo'." - "Set my profile bio and headline." - "Set my twitter handle to alexey_pelykh." - "Set my twitter to https://x.com/alexey_pelykh." (a URL is accepted; ttctl stores the bare handle) - "Clear my twitter handle." (call with `twitt…

Add a new certification entry (name + issuer, with optional issue / expiration dates, credential URL, and credential ID). Dates accept ISO-8601 (YYYY-MM-DD) or year-only (YYYY); month is preserved when given.

Toggle the highlight flag on a certification entry.

List every certification entry on the signed-in user's Toptal profile, with each row's full per-item shape (mirrors `ttctl_profile_certifications_show`). Example user prompts that should map to this tool: - "What certifications do I have on my Toptal profile?" - "Show me all my Toptal certifications." - "List my Toptal certification IDs so I can edit one."

Remove a certification entry by id.

Show a single certification entry by id (returns the row as JSON). Note: the underlying wire call lists all rows and filters client-side; the dry-run preview emits `GET_CERTIFICATION` (the list query) accordingly.

Update an existing certification entry by id. At least one field must be supplied.

List the Toptal Country/geography catalog (id, ISO code, name) — the full ~250-row catalog (not a search). Use this to resolve a valid Country id to pass as `primaryGeographyId` to ttctl_profile_employment_add / ttctl_profile_employment_update.

Add a new education entry. institution, degree, field of study, location, and start/end years are ALL required — the Toptal API rejects a create that omits any of them. Dates accept ISO-8601 (YYYY-MM-DD) or year-only (YYYY).

Toggle the highlight flag on an education entry.

List every education entry on the signed-in user's Toptal profile, with each row's full per-item shape (mirrors `ttctl_profile_education_show`). Example user prompts that should map to this tool: - "What education entries do I have on my Toptal profile?" - "Show me all my Toptal education history." - "List my Toptal education IDs so I can edit one."

Remove an education entry by id.

Show a single education entry by id (returns the row as JSON). Note: the underlying wire call lists all rows and filters client-side; the dry-run preview emits `GET_EDUCATION` (the list query) accordingly.

Update an existing education entry by id. At least one field must be supplied.

Add a new employment entry (company + role, with optional start/end years and `current` flag). The `company` string is resolved to the server-side `employerId` via the employer-autocomplete catalog: 0 matches or 2+ matches return a VALIDATION_ERROR with disambiguation guidance. Pass an explicit `employerId` to bypass autocomplete entirely. Set `noEmployer: true` for a custom (non-catalog) workplace — sends the free-text `company` with employerId:null and skips autocomplete (cannot be combined with `employerId`). On the `noEmployer:true` path the Toptal server requires an anchor: pass EITHER `w…

Search the known-employer catalog by name (e.g. "Google"). Returns up to `limit` suggestions with their canonical IDs.

Toggle the highlight flag on an employment entry.

List every employment entry on the signed-in user's Toptal profile, with each row's full per-item shape (mirrors `ttctl_profile_employment_show`). Each row includes `engagement` (link to a `TalentEngagement` when the row was logged against a Toptal engagement, otherwise null) and `isEnterpriseExperience` (boolean flag for enterprise-scoped roles, nullable for older rows) — #554. Each row also hydrates `employer` — the resolved employer-catalog card (`name`, `city`, `country`, `logoUrl`, `employeeCount`, `industries`), or null for custom (non-catalog) workplaces — #555. Example user prompts …

Remove an employment entry by id.

Search Toptal's reporting-to name catalog by name prefix. Returns up to `limit` `{id,name}` suggestions for `Employment.reportingTo`.

Show a single employment entry by id (returns the row as JSON). Note: the underlying wire call lists all rows and filters client-side; the dry-run preview emits `GET_WORK_EXPERIENCE` (the list query) accordingly.

Description is built at runtime.

Description is built at runtime.

Update an existing employment entry by id. At least one field must be supplied. `description` is multi-paragraph free-text and splits on blank lines. `industryIds`, when supplied, replaces the entry's entire industry set (omit to preserve the current set) — discover ids via `ttctl_profile_industries_autocomplete`. `skills`, when supplied, replaces the entry's entire catalog-skill set (omit to preserve the current set) — discover ids via `ttctl_profile_skills_list`. `from` / `to` accept ISO-8601 (YYYY-MM-DD) or year-only (YYYY); ttctl normalizes to year (YYYY) on the wire (#527) — the Toptal `E…

Read the advanced-profile-wizard status plus a summary of the talent's travel-visa list (count + IDs). Example user prompts that should map to this tool: - "What's the state of my advanced-profile wizard?" - "Have I finished the advanced profile setup?" - "Show me my travel-visa summary."

Toggle one or more of the three onboarding-readiness booleans (background-check, drug-test, time-tracking-tools). Caller-omitted fields default to the current server state. At least one field must be supplied. Example user prompts that should map to this tool: - "Opt me into background-check screening." - "Mark me as willing to use time-tracking tools." - "Toggle off the drug-test flag on my profile."

Read the three onboarding-readiness toggles (background-check, drug-test, time-tracking-tools) for the signed-in talent. Example user prompts that should map to this tool: - "Am I opted into background checks?" - "What's my onboarding-readiness state?" - "Show my custom requirements."

Read the per-section profile-readiness checklist (photo, basic info, skills, employments, portfolio, working hours, etc.) plus the rolled-up `submitAvailable` flag. Example user prompts that should map to this tool: - "Is my Toptal profile ready to submit?" - "Which sections still need work?" - "Show me my profile-readiness checklist."

List the platform's per-section 'do this next' recommendations for the signed-in talent. Each recommendation has a `type` discriminator and a small payload of scalar fields. Example user prompts that should map to this tool: - "What does Toptal recommend I improve on my profile?" - "What's next on my profile checklist?" - "Show me the recommendations for my profile."

Read the talent's stored external profile URLs (linkedin, github, website, twitter, behance, dribbble) plus the last talent-side edit timestamp. This is the READ counterpart of ttctl_profile_external_update — use it to inspect current URL state instead of a no-op update (a no-op update is a write-disguised-as-read). Example user prompts that should map to this tool: - "What are my current external profile links?" - "Show me my stored LinkedIn / GitHub / website URLs." - "What Twitter handle is on my Toptal profile?"

Set one or more external profile URLs (LinkedIn, GitHub, website, Behance, Dribbble) on the signed-in talent's profile. At least one field must be provided. Twitter / X is NOT settable here — set it via `ttctl_profile_basic_update` (which accepts a URL OR a bare handle). The live server rejects `twitter` on the `ExternalProfilesInput` type (#526); supplying `twitter` to this tool returns a VALIDATION_ERROR redirect (it is not silently dropped). The read-side `ttctl_profile_external_show` still surfaces the stored value. Example user prompts that should map to this tool: - "Update my Linked…

Add a new industry-profile entry to the user's profile (the user's authored domain-expertise entry). `name` becomes the title; `connection` becomes domainArea (the user's role within the industry, e.g. 'Backend' for the 'Healthcare' industry).

Link a catalog industry to one or more employment and/or portfolio rows so the public profile shows 'Industry X (at company Y, …)' rather than orphan tags. Resolve `industryId` via `ttctl_profile_industries_autocomplete`; resolve `employmentIds` via `ttctl_profile_employment_list` and `portfolioItemIds` via `ttctl_profile_portfolio_list`. At least one of `employmentIds` / `portfolioItemIds` is required. **DESTRUCTIVE**: this writes recruiter-visible industry tags onto profile rows. The caller MUST set `profileCapabilityConsentIssued: true` to authorize the mutation. See ADR-009 (ttctl) for th…

Search the known-industries catalog by name (e.g. "Healthcare"). Returns up to `limit` suggestions with their canonical IDs. Distinct from `industries_add` — this is a lookup leaf, not a write.

List the user's industry-profile entries (returns an array of rows as JSON).

Remove an industry-profile entry by id.

Show a single industry-profile entry by id (returns the row as JSON). Resolved via the `node()` GraphQL resolver — a true per-id lookup, distinct from certifications/education/employment `show` which list-and-filter client-side.

Update an existing industry-profile entry by id. At least one field must be supplied.

Create a new portfolio item. `title` is required; other fields are optional. Use `ttctl_profile_portfolio_upload_cover` first if you want to attach a cover image, then pass the resulting `coverImageCacheName` via the `coverImage` field on a follow-up `update` call (or supply via the underlying GraphQL input — currently the cover-then-create flow is two-step).

Set or clear the `highlight` flag on a portfolio item. Toptal caps highlighted portfolio items at 3 — setting `highlight: true` when 3 are already highlighted is rejected with a generic USER_ERROR ("Something went wrong. Please try again later."). Clear an existing highlight (`highlight: false`) first; call `ttctl_profile_portfolio_list` to see which items are currently highlighted (#542).

List the signed-in user's portfolio items (id, title, link, highlight, etc).

Remove a portfolio item by id.

Move a portfolio item to an absolute 0-based position. To compute relative-to-neighbour positions, list portfolio items first to find indices.

Update fields on an existing portfolio item by id. Only supplied fields are updated. `industryIds`, when supplied, replaces the item's entire industry set (omit to preserve). `skills`, when supplied, replaces the item's entire catalog-skill set (omit to preserve) — discover ids via `ttctl_profile_skills_list`.

Upload a cover image for the user's portfolio. Supply EITHER `filePath` (server-relative; preferred when the host has filesystem access — Claude Desktop, Claude Code) OR `content` (base64-encoded; for web-hosted clients without filesystem access). Returns `coverImageCacheName` and `coverImageUrl`; pass the cache name into a subsequent portfolio-add or portfolio-update call's `coverImage` field to bind the cover to a specific item. Server requires the image to be at least 750x500 px and under 5 MB.

Upload an arbitrary attachment file for the user's portfolio. Supply EITHER `filePath` (preferred when the host has filesystem access) OR `content` (base64). Returns `fileCacheName` and `fileUrl`.

Cancel any in-flight resume upload, clearing half-uploaded server-side state. Idempotent — returns success even when no upload is in flight. Pass `dryRun: true` to preview the request without firing.

Upload the user's resume (PDF or DOCX). Supply EITHER `filePath` (server-relative; preferred when the host has filesystem access — Claude Desktop, Claude Code) OR `content` (base64-encoded; for web-hosted clients without filesystem access). Returns `{ success: true }` on a server-confirmed success. Pass `dryRun: true` to preview the GraphQL operations envelope without firing.

Approve a single pending item within a section review. DESTRUCTIVE: approval is final per platform semantics. Run `ttctl_profile_reviews_list` first to obtain the three required IDs. Example user prompts that should map to this tool: - "Approve the suggested change to my education section item." - "Accept the pending edit on my employment item." - "Approve item ID xyz in review abc."

Approve all pending items within a section review. DESTRUCTIVE: approval is final per platform semantics. Run `ttctl_profile_reviews_list` first to obtain the section ID. Example user prompts that should map to this tool: - "Approve all the suggested changes to my skills section." - "Accept all pending edits in my employment section." - "Approve everything in section EDUCATION."

List pending section reviews for the signed-in talent. Each row carries the section-review ID, section name, requestedAt timestamp, and an `items` array (each with its own id, itemId, requestedAt). Returns an empty array when no reviews are pending. Example user prompts that should map to this tool: - "What's pending review on my profile?" - "Show me my section reviews." - "Are there any unapproved changes on my profile?"

Add a skill to the signed-in user's profile. Pass `name` alone — the tool searches the catalog and transparently binds to the matching catalog Skill on a single exact match (case-insensitive). If no catalog skill matches, a custom (non-catalog) skill is created from `name`. If ≥2 catalog skills match the name exactly, an actionable error lists the duplicates and you disambiguate by passing `skillId` (discoverable via `ttctl_profile_skills_autocomplete`). Proficiency dimensions (`rating`, `experience`, `public`) all have sensible defaults — pass them only when overriding. Defaults applied when…

Link an existing `ProfileSkillSet` to one of your employment, education, certification, or portfolio rows via the `addProfileSkillSetConnection` mutation. The link surfaces on your recruiter-visible public profile. **DESTRUCTIVE**: this writes a new skill→entity connection onto your public profile. Reverse with `ttctl_profile_skills_remove_connection` (per-edge unlink) or `ttctl_profile_skills_remove` (whole skill-set removal cascades all connections server-side). **Consent gate** (ADR-009 (ttctl) — `profile-capability` domain): the caller MUST set `profileCapabilityConsentIssued: true`. Aut…

Search the global Toptal skill catalog for entries matching `query` (suitable for disambiguating before calling `ttctl_profile_skills_add`). Results are scoped to skills the talent's vertical permits and exclude any ids passed in `withoutIds` (e.g., the talent's existing skills). Example user prompts that should map to this tool: - "Search Toptal's catalog for 'postgres' before I add it." - "Find skill names matching 'java'."

List every skill on the signed-in user's Toptal profile, with rating / experience / visibility / connection-count for each. Example user prompts that should map to this tool: - "What skills do I have on my Toptal profile?" - "List my Toptal skills with their ratings."

Fetch the signed-in user's skill-readiness checklist — the same heuristics the portal uses to gate the 'ready to apply' state on the skills section. Each boolean reflects a sub-criterion (expert proficiency count, items count, programming language present, etc.). Example user prompts that should map to this tool: - "Are my Toptal skills complete enough?" - "Tell me what's missing on my skills section."

Remove a skill from the signed-in user's profile by its `ProfileSkillSet` id (NOT the Skill catalog id). Get the id from `ttctl_profile_skills_list` first if you only know the skill name. Removal cascades to any connections (portfolio items, education, employment, certifications). Example user prompts that should map to this tool: - "Remove the TypeScript skill from my profile." (after looking up its id) - "Drop skill ss-abc123 from my profile."

Unlink a single connection from a `ProfileSkillSet` via the `removeProfileSkillSetConnection` mutation. Removes the recruiter-visible skill→entity edge without removing the whole skill-set; for cascading removal use `ttctl_profile_skills_remove`. **DESTRUCTIVE**: this removes a recruiter-visible skill→entity connection from your public profile. Re-link via `ttctl_profile_skills_add_connection`. **Consent gate** (ADR-009 (ttctl) — `profile-capability` domain): the caller MUST set `profileCapabilityConsentIssued: true`. Auto-filling without explicit user direction is FORBIDDEN. **Pre-flight d…

Fetch details of a single ProfileSkillSet by id — name, rating, experience, visibility, and the count of connection edges (linked portfolio items / employment / education / certifications). Example user prompts that should map to this tool: - "Show me the details of my TypeScript skill on Toptal." (after looking up its id) - "What's the rating and connection count for skill ss-abc123?"

Update one or more fields on an existing ProfileSkillSet — proficiency rating, years of experience, public/private visibility. At least one of `rating`, `experience`, or `public` must be supplied. Multi-flag updates fire sequential mutations; partial-failure surfaces as `PARTIAL_FAILURE` listing which fields landed. Dry-run note: returns `{ ok: true, dryRun: true, previews: [...] }` (plural `previews`) — one preview per mutation that would actually fire, in apply-path order (rating → experience → public). Example user prompts that should map to this tool: - "Mark TypeScript as expert level…

Apply for an additional Toptal specialization track (e.g. Marketplace, Expert Crowd) on top of existing memberships. Wraps the `ApplyForSpecialization` gateway-portal mutation. **DESTRUCTIVE**: this submits the talent's application to the named specialization track's review queue. No withdraw mutation exists on the wire — once submitted, the platform's compliance / training / recruiter-review workflow takes over. **Consent gate** (ADR-009 (ttctl) — `profile-capability` domain): the caller MUST set `profileCapabilityConsentIssued: true`. Auto-filling without explicit user direction is FORBIDD…

Read the talent's specialization badges (Core, Marketplace, Expert Crowd, etc.) and per-row metadata: id, slug, title, description, logoUrl, applicationStatus, eligibleJobsCount, applicationCompletedAt, and operations.apply.{callable, messages}. Wraps the `GetTalentSpecializations` gateway-portal op (mobile-gateway surface). Viewer-scoped — takes no input. Example user prompts that should map to this tool: - "Which Toptal specializations am I a member of?" - "Show me my specialization badges." - "Am I in Core? Marketplace?" - "What specializations could I apply for?"

Create a new travel-visa record. Both `countryId` and `visaType` are required; `expiryDate` is optional. Pass `dryRun: true` to preview the request.

List the signed-in user's travel-visa records (id, country, type, expiry). Pass `dryRun: true` to preview the request.

Remove a travel-visa record by id. Pass `dryRun: true` to preview the request.

Update fields on a travel-visa record by id. Only supplied fields are updated. Pass `dryRun: true` to preview the request.

Add free-text feedback to one of the signed-in user's Toptal surveys (post-interview `INTERVIEW_ENDED` feedback, NPS, engagement surveys, etc.) via the `AddSurveyFeedback` mutation. **DESTRUCTIVE & IRREVERSIBLE**: there is no un-feedback operation, and your feedback is routed to a third party (the interviewing client, the engagement, or Toptal). **Consent gate** (ADR-009 (ttctl) — `survey-submission` domain, shared with submit): the caller MUST set `surveySubmissionConsentIssued: true`. Auto-filling without explicit user direction is FORBIDDEN. The survey `kind` is resolved from `ttctl_surv…

List the signed-in user's pending Toptal surveys (post-interview `INTERVIEW_ENDED` feedback, NPS, engagement surveys, etc.). Each survey carries `id`, `kind` (e.g. INTERVIEW_ENDED, NPS, ENGAGEMENT_ENDED), `title`, `isMandatory`, `alreadyAnswered`, and `questions[]`. Each question carries `id`, `label`, `inputType`, `isMandatory`, and the selectable `answers[]` (`id` / `label` / `value`). `inputType` — NOT whether `answers[]` is empty — drives the answer value. Never infer the type from `answers[]`: an `OPEN_TEXT` question can arrive carrying a single sentinel option, so keying on emptiness m…

Submit structured answers to one of the signed-in user's pending Toptal surveys (post-interview `INTERVIEW_ENDED` feedback, NPS, engagement surveys, etc.) via the `SubmitSurvey` mutation. **DESTRUCTIVE & IRREVERSIBLE**: a submitted survey cannot be un-answered, and your feedback is routed to a third party (the interviewing client, the engagement, or Toptal). **Consent gate** (ADR-009 (ttctl) — `survey-submission` domain): the caller MUST set `surveySubmissionConsentIssued: true`. Auto-filling without explicit user direction is FORBIDDEN. **Pre-flight discovery** (`ttctl_surveys_list`): each…

List the signed-in user's Toptal Talent timesheet billing cycles. A timesheet is a per-billing-cycle bucket of time entries that the talent submits for client billing. Default scope: viewer-wide pending timesheets (what currently needs submission). Pass `engagement` (jobActivityItem.id from `engagements_list`) to scope to one engagement (returns ALL cycles for that engagement, regardless of submission state). For viewer-wide pagination, prefer `ttctl_timesheet_pending_list` (#374) — it exposes the wire's `limit` input surface-honestly. This tool keeps its pre-#374 shape (no pagination args) …

List the signed-in user's Toptal Talent viewer-wide pending billing cycles — the timesheets that currently need submission. Use this tool when the user wants to enumerate or paginate over their pending timesheets and `ttctl_timesheet_list` (no pagination args) returns a too-narrow window. **'Pending' here means pending SUBMISSION (by you), NOT pending approval (by the client).** This tool lists cycles you still need to submit. For approval state, read `timesheetApproved` / `timesheetRequiresApproval` on any cycle via `ttctl_timesheet_list` or `ttctl_timesheet_show`. **Pagination divergence**…

Fetch a single timesheet's full detail by BillingCycle.id (the id returned by `ttctl_timesheet_list`). Returns the cycle metadata (week range, hours, submission + approval state), the engagement+job reference, the rate agreement snapshot, the comment (if any), and the per-day time entries (`timesheetRecords`). Approval state: `timesheetApproved` (the client signed off), `timesheetRequiresApproval` (whether sign-off is needed at all), and the raw billing-cycle `status` — distinguishes 'submitted, awaiting the client' from 'approved'. Example user prompts: - "Show me the details of timesheet…

Batch-fetch several timesheets by id in a single wire round-trip — the bulk sibling of `ttctl_timesheet_show`. Returns the found timesheets in INPUT order; ids that resolve to no timesheet are omitted (diff the returned `id`s against the ids you passed). Accepts up to 20 ids. Returns LIST-ROW fields only (week range, hours, submission + approval state, engagement+job reference) — the same shape as `ttctl_timesheet_list`. It does NOT return the per-day `timesheetRecords`, comment, or rate-card that `ttctl_timesheet_show` returns. For a single timesheet's full detail, call `ttctl_timesheet_show…

Submit a timesheet (BillingCycle.id) for billing. The submission is one-way at the wire level — once submitted, the timesheet enters Toptal's billing pipeline and cannot be retracted from this CLI. **This is a write operation**. Confirm with the user BEFORE invoking, including the cycle id, week range, and hours about to be submitted. `id` is optional: omitted, the tool resolves the single currently-pending cycle whose submission window contains 'now'. If zero or multiple cycles match, the tool returns a structured error so the LLM can disambiguate before retrying with an explicit id. Optio…

Edit a draft timesheet (BillingCycle.id) — its comment and/or per-day time records. Use after the user wants to correct logged hours or fix a timesheet comment before submitting. **This is a write operation.** Confirm the change with the user first. **Full-replacement contract**: the wire op replaces the ENTIRE record set and comment, so this tool does read-modify-write — it fetches the current timesheet, merges your `records` overrides by date into the complete set, and resends everything. Days you don't mention are preserved, NOT cleared. Each `records` entry: `date` (YYYY-MM-DD), optional…