JobPilot is an HTTP-based job automation MCP server with 7 tools spanning job search and application workflows. However, the implementation has significant definition quality gaps. Most tools lack parameter descriptions, only platform, query, location, job_url, resume_path, and dry_run have descriptions; email and password parameters in login/login_indeed have no descriptions. Input schemas are present but minimal. Tool descriptions are present but generic (e.g., 'Search for jobs on the specified platform (LinkedIn or Indeed) based on query and location' for search_jobs is only 92 chars and does not explain WHEN to use it vs search_jobs_indeed, what it returns, or dependencies). Error handling is absent, no recovery guidance, no categorization of retryable vs fatal errors. The codebase shows defensive patterns (e.g., check if bot.page exists before closing) but these are not surfaced in tool definitions. No tool is marked with readOnlyHint/destructiveHint annotations despite clear semantic differences (apply_to_job is WRITE, search_jobs is READ_ONLY). Naming follows verb_noun convention (search_jobs, apply_to_job, login) which is positive, but there is functional duplication: both search_jobs (platform-agnostic wrapper) and search_jobs_indeed (platform-specific) are exposed, forcing the LLM to choose between them. Similarly, login and login_indeed are both exposed. Output schemas are not documented, JobResult is defined in the router but not returned explicitly in tool definitions.

• Consolidate search_jobs and search_jobs_indeed into a single search_jobs tool that accepts platform as a parameter. Remove the platform-specific duplicate. This reduces cognitive load for the LLM and prevents selection ambiguity.
• Similarly, consolidate login and login_indeed into a single login tool with platform parameter, and apply_to_job / apply_to_job_indeed into a single apply_to_job tool.
• Add complete parameter descriptions for email and password in login tools. Example: 'Email address or username for the platform account (must be pre-registered)'.
• Expand tool descriptions to 150-200 characters and include WHEN to use each tool, what it returns, and any dependencies. Example for search_jobs: 'Search for job listings on LinkedIn or Indeed. Returns up to 20 results with title, company, URL, and platform. Call this BEFORE apply_to_job to find jobs. Requires no prior login.'
• Document output schemas explicitly in tool definitions. For search_jobs, state: 'Returns an array of job objects: {title (string), company (string), url (string), platform (string)}. Results are paginated; use limit and offset parameters to retrieve additional pages.'
• Add actionable error handling guidance. Example: 'If platform is invalid, try "linkedin" or "indeed". If search returns 0 results, refine query or location.'
• Add tool annotations (readOnlyHint, destructiveHint, idempotentHint) to all tools. Mark search_* as readOnly=true, login as destructive=true (or dangerous), apply_to_job as destructive=true (unless dry_run=true).