Single tool with reasonable structure but significant gaps in descriptions and parameter constraints. Tool naming follows verb-noun pattern (get_jobs), which is positive. However, parameter descriptions lack critical detail about constraints, formats, and validation rules. The tool accepts external input without documented validation. Input schema is properly typed with arktype/JSON Schema, but several parameters lack sufficient description guidance for LLM selection and invocation.
Parameter 'sinceWhen' description includes inline example format 'e.g., 1d or 1w' instead of relying on the regex pattern constraint. This invites LLMs to treat examples as the complete valid set. Pattern '/^[0-9]+[dw]$/' is present in schema but not explained in description text.
No documented output schema. The tool returns a JSON object with a 'jobs' array, but the structure, fields, and types of each job object are not documented. LLMs cannot plan downstream operations or extract the right data without knowing what fields to expect (e.g., job_id, title, company, url, remote status, location, salary).
No pagination or result limit documented. The tool hardcodes limit=10 in the fetch body, but this is not visible to the LLM or documented in the description. If the API returns 10 items every time, the LLM cannot understand available pagination or request more results without a documented mechanism.
get_jobs
Recommendations
Document the complete output schema including field names, types, and descriptions. Example: 'Returns an array of job objects, each with fields: job_id (string), title (string), company (string), url (string), description (string), location (string), is_remote (boolean), posted_date (ISO 8601 string), salary_range (object with min/max), required_skills (array of strings).'
Expand tool description from 26 to 80 - 150 characters. Include WHEN to call this tool: 'Search for available jobs matching keywords and filters. Use to find opportunities by technology stack, remote status, or recency. Returns up to 10 results; call multiple times with different keywords for broader discovery.'
Add explicit parameter min/max constraints: 'keywords: array of 1 - 10 strings (case-insensitive partial matches); excludeKeywords: array of 0 - 10 strings; sinceWhen: one of 1d, 7d, 14d, 30d (days or weeks ago)'.
Move the hardcoded API URL into an environment variable (JOB_SEARCHOOR_API_URL or similar) and validate it at startup. Document the configuration requirement in README.
Replace inline examples ('e.g., 1d or 1w') with formal enum values or explicit text stating the regex pattern. For sinceWhen, document: 'Pattern: /^[0-9]+[dw]$/ meaning an integer followed by 'd' (days) or 'w' (weeks). Examples: 1d, 7d, 2w, 30d. Common values: 1d (last 24h), 1w (last 7d), 1m (last 30d).'
Add error handling guidance to the tool description: 'Returns an error object if the API is unreachable or parameters are invalid. If an error occurs, check that keywords are valid job titles/technologies and sinceWhen matches the required format.'
Tool description is only 26 characters ('Get the available jobs'). While within the functional range, it lacks actionable context: WHEN to use this tool, WHAT filtering options exist, and any prerequisites. Production tools average 194 chars. Baselines show 100% of A+ tools provide richer docstrings explaining the 'why' and 'when'.
Parameter descriptions lack constraint details. 'Keywords to filter jobs by' does not specify: minimum/maximum array length, whether duplicates are allowed, case sensitivity, or what constitutes a valid keyword.
No error handling guidance. The tool implementation returns a JSON response with an 'error' boolean field, but the tool description does not explain what errors are possible, what they mean, or what the LLM should do if an error occurs. Per pattern:recovery-guide, errors must be actionable.
External API URL is hardcoded in the tool implementation ('https://terribly-true-mullet.ngrok-free.app/get-jobs'). This is an ngrok proxy URL intended for temporary tunneling and is not suitable for production. The URL should be stored in environment variables and validated.
Tool implementation logs arguments to stderr ('console.error(args)'), which could expose sensitive query parameters if keywords or other filters contain user data. No audit trail or structured logging is present.
get_jobs
Document the hardcoded limit=10 in the tool description or expose it as an optional parameter with default: 'Results are limited to 10 jobs per call. For larger result sets, call multiple times with different keywords or filters.'
Remove or replace the console.error(args) logging with structured logging that does not expose raw parameters. Use a logger that writes only non-sensitive metadata (timestamp, tool name, execution time, success/failure) to stderr.
Consider splitting parameter handling: if keywords and excludeKeywords are always used together, document their interaction clearly. If they can conflict (e.g., 'typescript' in both), specify behavior: 'If a keyword appears in both keywords and excludeKeywords, excludeKeywords takes precedence.'
Add a 'limit' parameter (optional, default=10, max=100) if the API supports pagination, allowing LLMs to request larger result sets when needed. Document the tradeoff: 'Larger limits return more results but increase response time and token count.'