apply_template
ChatGPTAI-fill a LaTeX template with the cover letter content, compile to PDF, and upload to S3. Does not deduct credits. If the template has contact variables and variableValues is omitted or incomplete, returns status "needs_variables" instead of applying. Present a confirm-draft: list every required field; for status "saved" show the value and ask accept/edit; for "needs_input" ask only for that field (you may draft from suggestedVariableValues, CV/resume, or conversation — never invent). Surface privacyNote (safely stored, prompted only once), then call again with a complete variableValues map.
create_cover_letter
ChatGPTPrepare a new cover letter from a job description and candidate information. Deducts credits from the user account. Prefer list_user_job_listings → present company + position options (list has no job description) → wait for the user to pick one → pass that id as jobListingId (omit companyName/role/jobPosition). Call get_user_job_listing only if you need the full posting. Only collect full company/role/jobPosition when no saved listing applies (creates a new listing). Prefer previously uploaded files from list_user_files when any exist — pass them as files. If list_user_files returns none, draft a personBio when you already have grounded candidate data and present it for confirmation or edits; if you lack usable background, ask them for experience, skills, and education. Never invent experience, skills, or education. Wait for explicit confirm (or edited text), then call this tool with the confirmed personBio (omit files or pass []). Always note that uploading a CV at https://www.coverlttr.com/settings/files improves quality for this and future letters. Prefer get_user_profile (and optionally get_cover_letter_cost) first so you know the user can afford the generation. After success, tell the user to open the returned viewUrl on the website for a proper formatted view and easy access to templates.
export_file
ChatGPTExport an applied template to a specific format (pdf, docx, md, tex, or png). Creates a new applied template file entry.
get_cover_letter_cost
ChatGPTEstimate how many credits a cover letter generation would cost for the given inputs. Does not create a cover letter or deduct credits. Prefer list_user_job_listings first so the user can pick a saved job and you pass jobListingId (omit companyName/role/jobPosition). Optionally pass sourceCoverLetterId to include regeneration discounts. Pair with get_user_profile (creditsAmount) to confirm the user can afford generation before create_cover_letter.
get_download_url
ChatGPTGet a presigned S3 URL to download a specific applied template file by its ID. Format is read from the stored file.
get_user_file_url
ChatGPTGet a short-lived (2 min) presigned S3 URL to preview or download a previously uploaded user file (CV/resume) by its id from list_user_files.
get_user_job_listing
ChatGPTGet one saved job listing by id (GET /api/job-listings/{id}). Returns full detail: id, company, position/role, source, createdAt, plus description (the full job posting — same content as jobPosition on create_cover_letter). Use after list_user_job_listings when you need the job description; list_user_job_listings never returns this field. To generate a cover letter you can still pass this listing's id as jobListingId and omit companyName/role/jobPosition.
get_user_profile
ChatGPTReturn the authenticated user's profile: identity fields (email, firstName, lastName) for conversation context, plus available credits (creditsAmount) and subscription status. Read-only - does not change account state. Call this before create_cover_letter / regenerate_cover_letter (and optionally with get_cover_letter_cost) so you know whether the user can afford generation. Prefer this over asking the user for their balance.
get_user_variable_responses
ChatGPTReturn saved template contact field values for the authenticated user (GET /api/user/variable-responses), keyed by variable name (e.g. email_address, phone_number). Read-only - does not apply a template. Preview values still need user confirm on apply_template when a template has variables.
list_templates
ChatGPTList all LaTeX cover letter templates (GET /api/template). Optionally pass coverLetterId to include applied status for that letter. Each template includes a variables array (name, label, type, required, example, …) needed for apply_template. Prefer pointing the user to the cover letter page on the website for browsing and picking templates visually.
list_user_cover_letters
ChatGPTList the authenticated user's existing cover letters (GET /api/user/{id}/cover-letters). Returns id, title, company, role, language, version, and applied templates - not full letter body. Use early when the user wants to apply a template or export an existing letter rather than create a new one. Pass a cover letter id from this list to list_templates → apply_template → export_file. Prefer create_cover_letter only when they need a new letter for a job. Each item includes a viewUrl for the website.
list_user_files
ChatGPTList files previously uploaded by the user (CV, resume, etc.). Prefer passing these as the files array when calling create_cover_letter or regenerate_cover_letter so Gemini can analyze them. Use get_user_file_url with a file id to get a short-lived preview/download link. If no files are returned, draft a personBio from grounded candidate data when available and ask the user to confirm or edit it; otherwise ask for their background (experience, skills, education). Never invent experience. Always note that uploading a CV at https://www.coverlttr.com/settings/files improves quality for this and future letters; afterwards files will be available here.
list_user_job_listings
ChatGPTList the authenticated user's saved job listings (GET /api/job-listings?includeDescription=false). Returns minor details only: id, company (name/logo/etc.), position/role (job title), source, createdAt. Does not return the job posting body (description / jobPosition) — that floods context; call get_user_job_listing with an id when you need the full description. Present each option as company name + role, wait for the user to pick one, then pass that id as jobListingId to get_cover_letter_cost / create_cover_letter (omit companyName/role/jobPosition). Prefer this before asking for a full manual company/role/job description when the user may already have the job saved.
regenerate_cover_letter
ChatGPTRegenerate an existing cover letter with optional feedback. Creates a revision linked to the source cover letter. Deducts credits (regeneration discount may apply). You may pass jobListingId from list_user_job_listings (omit companyName/role/jobPosition) instead of sending full job fields. Prefer get_user_profile (and optionally get_cover_letter_cost with sourceCoverLetterId) first so you know the user can afford regeneration. After success, tell the user to open the returned viewUrl on the website for a proper formatted view and easy access to templates.
save_user_job_listing
ChatGPTSave a manual job listing for the authenticated user (POST /api/job-listings). Use when the user wants to store a company + role + description for later cover letters. After saving, pass the returned id as jobListingId to get_cover_letter_cost / create_cover_letter. Use get_user_job_listing if you need to read the stored job description later; list_user_job_listings will not return it.
