llmconveyors-mcp 0.3.1 → 0.3.2

package/dist/index.js

@@ -194,7 +194,7 @@ function registerAgentTools(server2, client2) {
   );
   server2.tool(
     "agent-status",
-    "Check the status of a running agent job. Requires scope: jobs:read or sales:read.",
+    "Poll the status of a running agent job to check progress, completion, or if it is awaiting input. Returns status, logs, and artifacts when available. Use this after calling job-hunter-run or b2b-sales-run to monitor the asynchronous job. When status is awaiting_input, use agent-interact to respond. Read-only, no side effects. Requires scope: jobs:read or sales:read.",
     {
       agentType: z.enum(["job-hunter", "b2b-sales"]).describe("Agent type"),
       jobId: z.string().describe("Job ID returned from a generate call"),
@@ -254,7 +254,7 @@ function registerAgentTools(server2, client2) {
   );
   server2.tool(
     "agent-manifest",
-    "Get the manifest (input fields, capabilities, billing) for an agent type. Requires scope: jobs:read or sales:read.",
+    "Get the manifest for an agent type, describing its input fields, capabilities, supported options, and billing information (credit costs per action). Use this to discover what parameters an agent accepts before running it, or to display pricing information. Read-only, no side effects. Requires scope: jobs:read or sales:read.",
     {
       agentType: z.enum(["job-hunter", "b2b-sales"]).describe("Agent type")
     },
@@ -274,7 +274,7 @@ import { z as z2 } from "zod";
 function registerAtsTools(server2, client2) {
   server2.tool(
     "ats-score",
-    "Score a resume against a job description for ATS compatibility. Returns overall score, grade, keyword matches, and improvement suggestions. Consumes credits. Requires scope: ats:write.",
+    "Score a resume against a job description for ATS (Applicant Tracking System) compatibility using a 3-pass hybrid analysis (keyword extraction, deterministic matching, semantic gap analysis). Returns an overall score, letter grade, matched/missing keywords, and actionable improvement suggestions. Use this before job-hunter-run to assess resume fit, or standalone to evaluate how well a resume matches a specific job posting. Consumes credits. Requires scope: ats:write. Use upload-job-text to parse a job description first if you have a URL.",
     {
       resumeText: z2.string().describe("Resume as plain text"),
       jobDescription: z2.string().describe("Job description as plain text"),
@@ -300,7 +300,7 @@ import { z as z3 } from "zod";
 function registerResumeTools(server2, client2) {
   server2.tool(
     "resume-parse",
-    "Parse a resume file into structured JSON Resume format. Accepts base64-encoded file content. Requires scope: resume:write.",
+    "Parse a resume file (PDF, DOCX, or TXT) into structured JSON Resume format. Accepts base64-encoded file content and returns structured data with contact info, work experience, education, and skills. Use this to extract structured data from an existing resume file. For uploading and parsing in one step, use upload-resume instead. Requires scope: resume:write.",
     {
       fileBase64: z3.string().describe("Base64-encoded resume file (PDF, DOCX, TXT)"),
       filename: z3.string().describe("Original filename with extension"),
@@ -323,7 +323,7 @@ function registerResumeTools(server2, client2) {
   );
   server2.tool(
     "resume-validate",
-    "Validate a resume in JSON Resume format. Returns validation errors and warnings. Requires scope: resume:write.",
+    "Validate a resume object against the JSON Resume schema, returning any errors and warnings (missing fields, invalid formats, incomplete sections). Use this after parsing or editing a resume to verify it is well-formed before rendering or submitting to agents. Does not modify the resume. Requires scope: resume:write.",
     {
       resume: z3.record(z3.unknown()).describe("Resume object in JSON Resume format")
     },
@@ -338,7 +338,7 @@ function registerResumeTools(server2, client2) {
   );
   server2.tool(
     "resume-render",
-    "Render a resume to PDF or HTML. Returns a URL to download the generated file. Requires scope: resume:write.",
+    "Render a JSON Resume object to a downloadable PDF or HTML file using a specified theme. Returns a URL to download the generated file. Use this to produce a polished, formatted resume for sharing or printing. Use resume-themes to see available themes. For a quick inline preview without generating a file, use resume-preview instead. Requires scope: resume:write.",
     {
       resume: z3.record(z3.unknown()).describe("Resume object in JSON Resume format"),
       theme: z3.string().describe("Theme name (e.g. even, stackoverflow, class, professional, elegant, macchiato, react, academic)"),
@@ -359,7 +359,7 @@ function registerResumeTools(server2, client2) {
   );
   server2.tool(
     "resume-preview",
-    "Preview a resume as HTML. Returns rendered HTML string. Requires scope: resume:write.",
+    "Preview a JSON Resume object as inline HTML using a specified theme. Returns the rendered HTML string directly (not a URL). Use this for quick visual previews without generating a downloadable file. For producing a downloadable PDF or HTML file, use resume-render instead. Requires scope: resume:write.",
     {
       resume: z3.record(z3.unknown()).describe("Resume object in JSON Resume format"),
       theme: z3.string().describe("Theme name (e.g. even, stackoverflow, class, professional)")
@@ -378,7 +378,7 @@ function registerResumeTools(server2, client2) {
   );
   server2.tool(
     "resume-themes",
-    "List all available resume themes. Returns theme IDs, names, and descriptions. Requires scope: resume:read.",
+    "List all available resume themes with their IDs, names, and descriptions. Use this to discover theme options before calling resume-render or resume-preview, or to let the user choose a theme. Read-only, no side effects. Requires scope: resume:read.",
     {},
     async () => {
       try {
@@ -391,7 +391,7 @@ function registerResumeTools(server2, client2) {
   );
   server2.tool(
     "resume-import-rx",
-    "Import a resume from Reactive Resume (RxResume) format into JSON Resume format. Requires scope: resume:write.",
+    "Convert a resume from Reactive Resume (RxResume) format into JSON Resume format. Use this to import resumes exported from the Reactive Resume application. Returns the converted resume object. Does not store the result; save it with master-resume-upsert if needed. Requires scope: resume:write. For the reverse conversion, use resume-export-rx.",
     {
       data: z3.record(z3.unknown()).describe("RxResume data object to import")
     },
@@ -406,7 +406,7 @@ function registerResumeTools(server2, client2) {
   );
   server2.tool(
     "resume-export-rx",
-    "Export a JSON Resume to Reactive Resume (RxResume) format. Requires scope: resume:read.",
+    "Convert a JSON Resume object to Reactive Resume (RxResume) format for use in the Reactive Resume application. Optionally include design/styling configuration. Read-only conversion, does not modify the source resume. Requires scope: resume:read. For the reverse conversion, use resume-import-rx.",
     {
       resume: z3.record(z3.unknown()).describe("Resume object in JSON Resume format"),
       designBlob: z3.record(z3.unknown()).optional().describe("Optional design/styling configuration")
@@ -425,7 +425,7 @@ function registerResumeTools(server2, client2) {
   );
   server2.tool(
     "master-resume-get",
-    "Get the user's master resume. Returns the master resume with label, rawText, and structuredData. Requires scope: resume:read.",
+    "Get the user's stored master resume, returning its label, raw text, and structured data. The master resume serves as the default resume for agent runs when no other resume is provided. Use this to review the current master resume before running job-hunter-run. Read-only, no side effects. Requires scope: resume:read. Use master-resume-upsert to create or update it.",
     {},
     async () => {
       try {
@@ -438,7 +438,7 @@ function registerResumeTools(server2, client2) {
   );
   server2.tool(
     "master-resume-upsert",
-    "Create or replace the user's master resume (upsert). Requires scope: resume:write.",
+    "Create or replace the user's master resume (upsert). The master resume is used as the default resume for job-hunter-run when no other resume is provided. Overwrites any existing master resume. Requires scope: resume:write. Use master-resume-get to check if one already exists. Use resume-parse to extract structured data from a file before saving.",
     {
       label: z3.string().describe("Label for the master resume"),
       rawText: z3.string().describe("Raw text content of the resume"),
@@ -459,7 +459,7 @@ function registerResumeTools(server2, client2) {
   );
   server2.tool(
     "master-resume-delete",
-    "Delete the user's master resume. Requires scope: resume:write.",
+    "Permanently delete the user's master resume. After deletion, agent runs will require a resume to be provided directly. This is irreversible. Requires scope: resume:write. Use master-resume-get to review the resume before deleting.",
     {},
     async () => {
       try {
@@ -477,7 +477,7 @@ import { z as z4 } from "zod";
 function registerUploadTools(server2, client2) {
   server2.tool(
     "upload-resume",
-    "Upload and parse a resume file. Accepts base64-encoded file content. Returns parsed resume data. Requires scope: upload:write.",
+    "Upload a resume file (PDF, DOCX, TXT) as base64-encoded content and parse it into structured data. Returns extracted contact info, work experience, education, and skills. Use this as the first step in a job application workflow before running ats-score or job-hunter-run. Max file size ~10 MB. Requires scope: upload:write. For parsing without the upload step, use resume-parse instead.",
     {
       fileBase64: z4.string().max(13981014).describe("Base64-encoded file content (PDF, DOCX, etc.) \u2014 max ~10 MB"),
       filename: z4.string().describe("Original filename with extension (e.g. resume.pdf)"),
@@ -498,7 +498,7 @@ function registerUploadTools(server2, client2) {
   );
   server2.tool(
     "upload-job-file",
-    "Upload and parse a job description file. Accepts base64-encoded file content. Returns parsed job data. Requires scope: upload:write.",
+    "Upload a job description file (PDF, DOCX, TXT) as base64-encoded content and parse it into structured job data. Returns extracted job title, requirements, qualifications, and company info. Use this when the job description is in a file rather than plain text. Max file size ~10 MB. Requires scope: upload:write. For plain text or URL-based job descriptions, use upload-job-text instead.",
     {
       fileBase64: z4.string().max(13981014).describe("Base64-encoded file content (PDF, DOCX, etc.) \u2014 max ~10 MB"),
       filename: z4.string().describe("Original filename with extension"),
@@ -519,7 +519,7 @@ function registerUploadTools(server2, client2) {
   );
   server2.tool(
     "upload-job-text",
-    "Upload a job description as plain text or fetch from a URL. At least one of text or url is required. Returns parsed job data. Requires scope: upload:write.",
+    "Parse a job description from plain text or fetch and parse from a URL. Returns structured job data including title, requirements, and qualifications. Use this when you have the job description as text or a URL to a job posting page. At least one of text or url is required. Requires scope: upload:write. For file-based job descriptions (PDF, DOCX), use upload-job-file instead.",
     {
       text: z4.string().max(5e4).optional().describe("Job description text (max 50K characters). Required if url is not provided."),
       url: z4.string().url().max(2048).optional().describe("URL to fetch job description from. Required if text is not provided."),
@@ -551,7 +551,7 @@ import { z as z5 } from "zod";
 function registerSessionTools(server2, client2) {
   server2.tool(
     "session-create",
-    "Create a new session. Returns the created session object with its ID. Requires scope: sessions:write.",
+    "Create a new session for grouping agent runs and their artifacts. Returns the session object with its ID. Sessions organize multiple generations (agent runs) into a logical workspace. Use this before running job-hunter-run or b2b-sales-run with a specific sessionId. Requires scope: sessions:write.",
     {
       sessionId: z5.string().optional().describe("Optional client-generated session ID"),
       metadata: z5.record(z5.unknown()).optional().describe("Optional session metadata")
@@ -570,7 +570,7 @@ function registerSessionTools(server2, client2) {
   );
   server2.tool(
     "session-list",
-    "List sessions with cursor-based pagination. Returns an array of session objects (or paginated envelope when limit is provided). Requires scope: sessions:read.",
+    "List sessions with cursor-based pagination. Returns session objects with IDs, creation dates, and metadata. Use this to browse existing sessions or find a session to resume. When limit is provided, returns a paginated envelope with a cursor for the next page. Read-only, no side effects. Requires scope: sessions:read. Use session-get or session-hydrate to get full details for a specific session.",
     {
       cursor: z5.string().optional().describe("Cursor for pagination (ISO 8601 datetime string)"),
       limit: z5.number().min(1).max(50).optional().describe("Number of sessions per page (1-50)")
@@ -589,7 +589,7 @@ function registerSessionTools(server2, client2) {
   );
   server2.tool(
     "session-get",
-    "Get a session by ID. Returns the session object with generation history. Requires scope: sessions:read.",
+    "Get a session by ID, returning the session object with its generation history (list of agent runs). Use this to check what generations exist in a session without loading full artifacts. Read-only, no side effects. Requires scope: sessions:read. For full session data including all artifacts and logs, use session-hydrate instead.",
     {
       id: z5.string().describe("Session ID")
     },
@@ -604,7 +604,7 @@ function registerSessionTools(server2, client2) {
   );
   server2.tool(
     "session-hydrate",
-    "Hydrate a session \u2014 returns the full session with all artifacts and logs. Requires scope: sessions:read.",
+    "Load a session with all its artifacts, logs, and generation details. Returns the complete session state including generated CVs, cover letters, emails, and conversation history. Use this to review full agent outputs or prepare artifacts for download. Heavier than session-get, so prefer session-get for lightweight lookups. Read-only, no side effects. Requires scope: sessions:read.",
     {
       id: z5.string().describe("Session ID")
     },
@@ -619,7 +619,7 @@ function registerSessionTools(server2, client2) {
   );
   server2.tool(
     "session-download",
-    "Download an artifact from a session by its storage key. Returns base64-encoded content for binary files (PDF, DOCX, images) or plain text for text files. Requires scope: sessions:read.",
+    "Download a specific artifact from a session by its storage key. Returns base64-encoded content for binary files (PDF, DOCX, images) or plain text for text files. Use this to retrieve individual generated files like a rendered PDF resume or cover letter. Get artifact keys from session-hydrate first. Read-only, no side effects. Requires scope: sessions:read. For downloading by storage path instead of session context, use document-download.",
     {
       id: z5.string().describe("Session ID"),
       key: z5.string().describe("Artifact storage key from session hydration")
@@ -651,7 +651,7 @@ function registerSessionTools(server2, client2) {
   );
   server2.tool(
     "session-delete",
-    "Delete a session by ID. Requires scope: sessions:write.",
+    "Permanently delete a session and all its generations, artifacts, and logs. This is irreversible. Use this to clean up completed or unwanted sessions. Requires scope: sessions:write. Use session-list to find sessions, and session-hydrate to review contents before deleting.",
     {
       id: z5.string().describe("Session ID")
     },
@@ -666,7 +666,7 @@ function registerSessionTools(server2, client2) {
   );
   server2.tool(
     "session-init",
-    "Initialize session configuration \u2014 returns default settings and capabilities. Requires scope: sessions:read.",
+    "Get the default session configuration, including available agent types, supported features, and default settings. Use this to discover what agents and capabilities are available before creating sessions. Read-only, no side effects. Requires scope: sessions:read.",
     {},
     async () => {
       try {
@@ -679,7 +679,7 @@ function registerSessionTools(server2, client2) {
   );
   server2.tool(
     "session-log",
-    "Append a log entry to a session. Used for tracking conversation history and tool usage. Requires scope: sessions:write.",
+    "Append a log entry to an existing session for tracking conversation history, tool usage, or status updates. Creates a new log record in the session. Use this to maintain an audit trail of actions taken during a session. Requires scope: sessions:write. Use session-hydrate to read back the full log history.",
     {
       id: z5.string().describe("Session ID"),
       role: z5.enum(["user", "assistant", "system", "tool", "status"]).describe("Log entry role"),
@@ -701,7 +701,7 @@ function registerSessionTools(server2, client2) {
   );
   server2.tool(
     "session-stats",
-    "Get session statistics (total sessions, active sequences, emails drafted, reply rate, credits used). Requires scope: sessions:read.",
+    "Get aggregate session statistics for an agent type, including total sessions, active sequences, emails drafted, reply rate, and credits consumed. Use this to review overall usage and performance metrics for job-hunter or b2b-sales workflows. Read-only, no side effects. Requires scope: sessions:read.",
     {
       agentType: z5.enum(["job-hunter", "b2b-sales"]).describe("Agent type to get stats for")
     },
@@ -723,7 +723,7 @@ import { z as z6 } from "zod";
 function registerSettingsTools(server2, client2) {
   server2.tool(
     "settings-profile",
-    "Get the current user's profile. Returns email, name, plan, and credit balance. Requires scope: settings:read.",
+    "Get the current user's profile including email, name, subscription plan, and remaining credit balance. Use this to check available credits before running agents (job-hunter-run, b2b-sales-run) or to verify account identity. Read-only, no side effects. Requires scope: settings:read. For detailed usage breakdown, use settings-usage-summary instead.",
     {},
     async () => {
       try {
@@ -736,7 +736,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "settings-preferences-get",
-    "Get the current user's preferences. Requires scope: settings:read.",
+    "Get the current user's preferences, optionally filtered by agent type. Returns configuration like default themes, generation settings, and notification preferences. Read-only, no side effects. Requires scope: settings:read. Use settings-preferences-update to modify preferences.",
     {
       agentType: z6.string().optional().describe("Filter preferences by agent type (e.g. job-hunter, b2b-sales)")
     },
@@ -753,7 +753,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "settings-preferences-update",
-    "Update the current user's preferences. Returns the updated preferences. Requires scope: settings:write.",
+    "Update the current user's preferences, optionally scoped to a specific agent type. Modifies stored preferences and returns the updated values. Use this to configure default themes, generation settings, or notification preferences. Requires scope: settings:write. Use settings-preferences-get first to see current values before updating.",
     {
       preferences: z6.record(z6.unknown()).describe("Preferences object to update"),
       agentType: z6.string().optional().describe("Agent type to scope preferences to (e.g. job-hunter, b2b-sales)")
@@ -772,7 +772,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "settings-usage-summary",
-    "Get a summary of the user's API usage and credit consumption. Requires scope: settings:read.",
+    "Get an aggregate summary of the user's API usage and credit consumption, including total credits used, remaining balance, and usage by category. Use this to check credit balance before running agents or to monitor spending. Read-only, no side effects. Requires scope: settings:read. For individual usage entries with timestamps, use settings-usage-logs instead.",
     {},
     async () => {
       try {
@@ -785,7 +785,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "settings-usage-logs",
-    "Get paginated usage logs. Returns individual usage entries with action, credits, and timestamps. Requires scope: settings:read.",
+    "Get paginated usage logs showing individual entries with action type, credits consumed, and timestamps. Use this to audit specific credit charges or investigate unexpected usage. Read-only, no side effects. Requires scope: settings:read. For an aggregate overview, use settings-usage-summary instead.",
     {
       offset: z6.number().optional().describe("Offset for pagination"),
       limit: z6.number().max(100).optional().describe("Number of entries to return (max 100)")
@@ -804,7 +804,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "api-key-create",
-    "Create a new platform API key. The key value is shown ONLY in this response -- save it immediately. Requires scope: settings:write.",
+    "Create a new platform API key with specified permission scopes. The key value is returned ONLY in this response and cannot be retrieved later, so save it immediately. Creates a new key record. Requires scope: settings:write. Use api-key-list to see existing keys. Use api-key-revoke to delete keys you no longer need.",
     {
       label: z6.string().describe("Human-readable label for the API key"),
       scopes: z6.array(z6.enum([
@@ -845,7 +845,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "api-key-list",
-    "List all platform API keys. Returns key metadata (hash, name, scopes) -- NOT the key values. Requires scope: settings:read.",
+    "List all platform API keys for the current user. Returns key metadata (hash, label, scopes, creation date) but NOT the actual key values (those are only shown at creation time). Use this to find key hashes for revocation, rotation, or usage queries. Read-only, no side effects. Requires scope: settings:read.",
     {},
     async () => {
       try {
@@ -858,7 +858,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "api-key-revoke",
-    "Revoke (delete) a platform API key by its hash. Requires scope: settings:write.",
+    "Permanently revoke and delete a platform API key by its hash. The key immediately stops working for all API calls. This is irreversible. Use this to remove compromised or unused keys. Requires scope: settings:write. Use api-key-list first to find the key hash. For replacing a key with a new one, use api-key-rotate instead.",
     {
       hash: z6.string().describe("API key hash to revoke")
     },
@@ -873,7 +873,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "api-key-rotate",
-    "Rotate a platform API key -- revokes the old key and returns a new one. Save the new key immediately. Requires scope: settings:write.",
+    "Rotate a platform API key by revoking the old key and issuing a new one. The new key value is returned ONLY in this response, so save it immediately. An optional grace period keeps the old key valid during transition. Use this for periodic key rotation or when a key may be compromised but you need continuity. Requires scope: settings:write. For immediate revocation without replacement, use api-key-revoke instead.",
     {
       hash: z6.string().describe("API key hash to rotate"),
       gracePeriodHours: z6.number().optional().describe("Hours the old key remains valid after rotation (default: 24)")
@@ -892,7 +892,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "api-key-usage",
-    "Get usage statistics for a specific API key by its hash. Requires scope: settings:read.",
+    "Get usage statistics for a specific API key by its hash, including request counts and credit consumption. Use this to monitor per-key usage or identify which key is consuming the most credits. Read-only, no side effects. Requires scope: settings:read. Use api-key-list to find key hashes.",
     {
       hash: z6.string().describe("API key hash")
     },
@@ -907,7 +907,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "byo-key-get",
-    "Get the status of all configured BYO provider keys. Returns provider names and their configuration status. Requires scope: settings:read.",
+    "Check the configuration status of all Bring Your Own (BYO) API keys. Returns each provider name and whether a key is configured. Use this to verify BYO key setup before running agents with tier=byo. Read-only, no side effects. Requires scope: settings:read. Use settings-supported-providers to see which providers are available. Use byo-key-set to configure a key.",
     {},
     async () => {
       try {
@@ -920,7 +920,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "byo-key-set",
-    "Set a Bring Your Own API key for a provider (e.g. gemini). BYO tier users get unlimited AI generation but still pay for contact enrichment. Requires scope: settings:write.",
+    "Configure a Bring Your Own (BYO) API key for an AI provider (e.g. gemini). BYO tier users get unlimited AI generation but still pay for contact enrichment credits. Stores the key securely on the platform. Requires scope: settings:write. Use settings-supported-providers to see available providers. Use byo-key-get to check current configuration. Use byo-key-remove to delete a configured key.",
     {
       provider: z6.string().describe("Provider name (e.g. gemini)"),
       apiKey: z6.string().describe("The API key to set"),
@@ -940,7 +940,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "byo-key-remove",
-    "Remove the configured BYO API key for a provider. Requires scope: settings:write.",
+    "Remove a configured Bring Your Own (BYO) API key for a provider. After removal, agent runs will use platform credits instead of the BYO key. Requires scope: settings:write. Use byo-key-get to check which providers have keys configured before removing.",
     {
       provider: z6.string().describe("Provider name to remove the key for (e.g. gemini)")
     },
@@ -955,7 +955,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "settings-supported-providers",
-    "List supported BYO key providers. Returns provider names and status. Requires scope: settings:read.",
+    "List all AI providers that support Bring Your Own (BYO) API keys, including provider names and availability status. Use this to discover which providers can be configured with byo-key-set before setting up BYO keys. Read-only, no side effects. Requires scope: settings:read.",
     {},
     async () => {
       try {
@@ -968,7 +968,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "webhook-secret-get",
-    "Get the current webhook secret for verifying webhook signatures. Requires scope: webhook:read.",
+    "Get the current webhook signing secret used to verify webhook payloads from the LLM Conveyors platform. Use this when setting up webhook receivers to validate that incoming webhooks are authentic. Read-only, no side effects. Requires scope: webhook:read. Use webhook-secret-rotate to generate a new secret if the current one is compromised.",
     {},
     async () => {
       try {
@@ -981,7 +981,7 @@ function registerSettingsTools(server2, client2) {
   );
   server2.tool(
     "webhook-secret-rotate",
-    "Rotate the webhook secret. Returns the new secret. The old secret is immediately invalidated. Rate limited: 5 per hour. Requires scope: webhook:write.",
+    "Rotate the webhook signing secret, generating a new one and immediately invalidating the old secret. All existing webhook receivers must be updated with the new secret or they will reject incoming payloads. Rate limited: 5 per hour. Requires scope: webhook:write. Use webhook-secret-get to retrieve the current secret before rotating.",
     {},
     async () => {
       try {
@@ -999,7 +999,7 @@ import { z as z7 } from "zod";
 function registerContentTools(server2, client2) {
   server2.tool(
     "content-save",
-    "Save a source document for use as context in AI generation. Returns success status. Requires scope: sessions:write.",
+    "Save a source document that will be used as context in future AI generation runs (job-hunter-run, b2b-sales-run). Overwrites any existing document of the same type. Use this to store your CV, cover letter templates, or strategy documents before running agents. Requires scope: sessions:write. Use content-list-sources to see what is already saved. Use content-get-source to read a specific saved document.",
     {
       docType: z7.enum([
         "original_cv",
@@ -1027,7 +1027,7 @@ function registerContentTools(server2, client2) {
   );
   server2.tool(
     "content-delete-generation",
-    "Delete a generation and all its artifacts from a session. Requires scope: sessions:write.",
+    "Permanently delete a generation and all its artifacts (CV, cover letter, emails) from a session. This is irreversible and removes all files associated with that generation. Use this to clean up unwanted outputs. Requires scope: sessions:write. Use session-hydrate first to review the generation before deleting.",
     {
       id: z7.string().describe("Generation ID to delete"),
       sessionId: z7.string().describe("Session ID that owns the generation")
@@ -1043,7 +1043,7 @@ function registerContentTools(server2, client2) {
   );
   server2.tool(
     "content-research-sender",
-    "Research and create a sender profile for content generation. Returns sender context. Requires scope: sessions:write. At least one of companyWebsite or companyName must be provided.",
+    "Research a company and create a sender profile for personalized content generation. Returns structured sender context (company info, positioning, value propositions). Use this before b2b-sales-run to pre-populate sender context for better outreach personalization. Consumes credits. At least one of companyWebsite or companyName must be provided. Requires scope: sessions:write.",
     {
       companyWebsite: z7.string().optional().describe("Company website to research"),
       companyName: z7.string().optional().describe("Company name for context")
@@ -1068,7 +1068,7 @@ function registerContentTools(server2, client2) {
   );
   server2.tool(
     "content-list-sources",
-    "List all saved source documents used as context for AI generation. Requires scope: sessions:read.",
+    "List all saved source documents used as context for AI generation, showing document types and metadata. Use this to check what context documents are available before running agents. Read-only, no side effects. Requires scope: sessions:read. Use content-get-source to read a specific document. Use content-save to add or update documents.",
     {},
     async () => {
       try {
@@ -1081,7 +1081,7 @@ function registerContentTools(server2, client2) {
   );
   server2.tool(
     "content-get-source",
-    "Get a specific source document by type. Requires scope: sessions:read.",
+    "Retrieve the full content of a specific saved source document by type (e.g. original_cv, cv_strategy, cold_email_strategy). Use this to review or display a previously saved context document. Read-only, no side effects. Requires scope: sessions:read. Use content-list-sources to see all available document types.",
     {
       docType: z7.enum([
         "original_cv",
@@ -1105,7 +1105,7 @@ function registerContentTools(server2, client2) {
   );
   server2.tool(
     "content-delete-source",
-    "Delete a source document by type. Requires scope: sessions:write.",
+    "Permanently delete a saved source document by type. Future agent runs will no longer use this document as context. Use this to remove outdated context documents before saving new ones. Requires scope: sessions:write. Use content-list-sources to verify which documents exist before deleting.",
     {
       docType: z7.enum([
         "original_cv",
@@ -1134,7 +1134,7 @@ import { z as z8 } from "zod";
 function registerSharesTools(server2, client2) {
   server2.tool(
     "share-create",
-    "Create a shareable public link for a generation's artifacts. Returns a slug and public URL. Requires scope: sessions:read.",
+    "Create a shareable public link for a generation's artifacts (resume, cover letter, emails). Returns a slug and public URL that anyone can view without authentication. Creates a new share record. Requires scope: sessions:read. Use after running job-hunter-run or b2b-sales-run to share the output. Use share-slug-stats to track views.",
     {
       sessionId: z8.string().describe("Session ID containing the generation"),
       generationId: z8.string().describe("Generation ID to share")
@@ -1153,7 +1153,7 @@ function registerSharesTools(server2, client2) {
   );
   server2.tool(
     "share-stats",
-    "Get statistics about your shared links (view counts, etc.). Requires scope: sessions:read.",
+    "Get aggregate statistics about all shared links for the current user, including total shares and total views. Use this for an overview of sharing activity. Read-only, no side effects. Requires scope: sessions:read. For per-link stats, use share-slug-stats with a specific slug.",
     {},
     async () => {
       try {
@@ -1166,7 +1166,7 @@ function registerSharesTools(server2, client2) {
   );
   server2.tool(
     "share-get-public",
-    "Get a publicly shared resource by its slug. No auth required (public endpoint).",
+    "Retrieve a publicly shared resource by its slug. Returns the shared artifacts (resume, cover letter, emails) without requiring authentication. Use this to view what a share link contains. Read-only, no side effects. No auth required (public endpoint).",
     {
       slug: z8.string().describe("Public share slug")
     },
@@ -1181,7 +1181,7 @@ function registerSharesTools(server2, client2) {
   );
   server2.tool(
     "share-slug-stats",
-    "Get visit statistics for a specific share link (owner only). Requires scope: sessions:read.",
+    "Get visit statistics for a specific share link, including view count and visit timestamps. Only accessible by the share owner. Use this to track engagement on a specific shared artifact. Read-only, no side effects. Requires scope: sessions:read. For aggregate stats across all shares, use share-stats instead.",
     {
       slug: z8.string().describe("Share link slug")
     },
@@ -1201,7 +1201,7 @@ import { z as z9 } from "zod";
 function registerDocumentTools(server2, client2) {
   server2.tool(
     "document-download",
-    "Download a document by its storage path. Returns base64-encoded content for binary files (PDF, DOCX, images) or plain text for text files. Requires scope: sessions:read.",
+    "Download a document artifact by its storage path. Returns base64-encoded content for binary files (PDF, DOCX, images) or plain text for text files. Use this to retrieve generated artifacts like rendered resumes or reports when you have the storage path. For downloading artifacts from a specific session, use session-download instead (which takes a session ID and artifact key). Read-only, no side effects. Requires scope: sessions:read.",
     {
       path: z9.string().describe("Document storage path")
     },
@@ -1237,7 +1237,7 @@ import { z as z10 } from "zod";
 function registerReferralTools(server2, client2) {
   server2.tool(
     "referral-stats",
-    "Get referral program statistics including total referrals and credits earned. Requires scope: settings:read.",
+    "Get referral program statistics for the current user, including total referrals, successful conversions, and credits earned. Use this to check referral performance or display earnings. Read-only, no side effects. Requires scope: settings:read. Use referral-code to get the shareable referral link.",
     {},
     async () => {
       try {
@@ -1250,7 +1250,7 @@ function registerReferralTools(server2, client2) {
   );
   server2.tool(
     "referral-code",
-    "Get your referral code for sharing with others. Requires scope: settings:read.",
+    "Get the current user's referral code and shareable referral link. Use this to retrieve the code for sharing with others. Read-only, no side effects. Requires scope: settings:read. To customize the code, use referral-vanity-code. To check referral performance, use referral-stats.",
     {},
     async () => {
       try {
@@ -1263,7 +1263,7 @@ function registerReferralTools(server2, client2) {
   );
   server2.tool(
     "referral-vanity-code",
-    "Set a custom vanity code for your referral link. Rate limited: 5 per hour. Requires scope: settings:write.",
+    "Set a custom vanity code for the user's referral link, replacing the auto-generated code. This permanently changes the referral URL. Rate limited: 5 per hour. Requires scope: settings:write. Use referral-code first to see the current code before changing it.",
     {
       code: z10.string().describe("Custom vanity code to set")
     },
@@ -1291,7 +1291,7 @@ var CONSENT_PURPOSES = [
 function registerPrivacyTools(server2, client2) {
   server2.tool(
     "privacy-list-consents",
-    "List all privacy consent statuses for the current user. Returns consent purposes and their granted/revoked status. Requires scope: settings:read.",
+    "List all privacy consent records for the current user, showing each data processing purpose and whether consent is granted or revoked. Use this to check consent status before running tools that require specific consents (e.g. ai-generation, contact-enrichment). Read-only, no side effects. Requires scope: settings:read.",
     {},
     async () => {
       try {
@@ -1304,7 +1304,7 @@ function registerPrivacyTools(server2, client2) {
   );
   server2.tool(
     "privacy-grant-consent",
-    "Grant consent for a specific data processing purpose. Requires scope: settings:write.",
+    "Grant consent for a specific data processing purpose. This enables the platform to process data for that purpose (e.g. ai-generation enables agent runs, contact-enrichment enables contact lookups). Modifies the user's consent record. Requires scope: settings:write. Use privacy-list-consents to check current status first. Use privacy-revoke-consent to undo.",
     {
       purpose: z11.enum(CONSENT_PURPOSES).describe("Consent purpose to grant")
     },
@@ -1319,7 +1319,7 @@ function registerPrivacyTools(server2, client2) {
   );
   server2.tool(
     "privacy-revoke-consent",
-    "Revoke consent for a specific data processing purpose. Requires scope: settings:write.",
+    "Revoke a previously granted consent for a specific data processing purpose. This may disable platform features that depend on that consent (e.g. revoking ai-generation prevents agent runs). Modifies the user's consent record. Requires scope: settings:write. Use privacy-list-consents to check current status first.",
     {
       purpose: z11.enum(CONSENT_PURPOSES).describe("Consent purpose to revoke")
     },
@@ -1338,7 +1338,7 @@ function registerPrivacyTools(server2, client2) {
 function registerHealthTools(server2, client2) {
   server2.tool(
     "health-root",
-    "Get API root info (name, version). Public endpoint, no auth required.",
+    "Get the LLM Conveyors API server name and version. Use this to verify the MCP server is connected and reachable before running other tools. No authentication required. Returns JSON with name and version fields. For deeper diagnostics, use health-check instead.",
     {},
     async () => {
       try {
@@ -1351,7 +1351,7 @@ function registerHealthTools(server2, client2) {
   );
   server2.tool(
     "health-check",
-    "Check API health status \u2014 returns status, timestamp, uptime, version, checks, memory. Public endpoint, no auth required.",
+    "Run a detailed health check on the LLM Conveyors API, returning status, uptime, version, dependency checks, and memory usage. Use this to diagnose connectivity or performance issues before retrying failed tool calls. No authentication required. For a simple alive/dead check, use health-live instead.",
     {},
     async () => {
       try {
@@ -1364,7 +1364,7 @@ function registerHealthTools(server2, client2) {
   );
   server2.tool(
     "health-ready",
-    "Check API readiness. Public endpoint, no auth required.",
+    "Check whether the LLM Conveyors API is ready to accept requests (all dependencies initialized). Use this in automation pipelines to wait for readiness before sending agent runs. No authentication required. Returns a simple ready/not-ready status. For process liveness only, use health-live instead.",
     {},
     async () => {
       try {
@@ -1377,7 +1377,7 @@ function registerHealthTools(server2, client2) {
   );
   server2.tool(
     "health-live",
-    "Check API liveness. Public endpoint, no auth required.",
+    "Check whether the LLM Conveyors API process is alive and responding. Use this as a lightweight heartbeat check in monitoring or retry loops. No authentication required. Returns a simple alive status. For dependency-level diagnostics, use health-check instead.",
     {},
     async () => {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llmconveyors-mcp",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "mcpName": "io.github.ebenezer-isaac/llmconveyors",
   "description": "MCP server that connects AI agents to LLM Conveyors — run Job Hunter, B2B Sales, and other AI agents from Claude, Cursor, or any MCP client",
   "type": "module",