The server exposes 4 well-defined job orchestration tools with complete JSON Schema input definitions. All tools have descriptions and most parameters are typed with descriptions. However, there are critical gaps: (1) No output schemas are documented anywhere, LLMs cannot see what these tools return, forcing them to guess at downstream field names and types. (2) The joblet_run_job tool is complex with 18 parameters, but several lack clear constraints, ranges, or enum values (e.g., 'network', 'runtime' are free-form strings). (3) Parameter descriptions are present but often minimal (10-30 chars), providing weak guidance for LLM selection. (4) No error handling documentation, what happens if a job fails to start, times out, or hits resource limits? (5) Tool descriptions are generic and don't explain WHEN to use each tool vs. alternatives or what preconditions exist. The joblet_run_job description ('Execute a new job with resource specifications') tells the LLM almost nothing about when vs. schedule a deferred job or list existing ones.
No output schemas documented for any tool. LLMs cannot predict what fields a job object contains, making it impossible to compose multi-step job workflows or extract the right IDs for downstream calls.
joblet_run_job tool description ('Execute a new job with resource specifications') is generic and does not explain WHEN to use it, what distinguishes it from scheduling, or what the return value contains. Agents cannot determine if this is the right tool without reading implementation.
joblet_run_job has 18 parameters with minimal descriptions. 'network', 'runtime', 'work_dir' are free-form strings with no enum constraints, format hints, or examples. Agents cannot predict valid values and will likely pass invalid inputs.
joblet_run_job
Recommendations
Document the output schema for each tool. For joblet_run_job, define the Job object structure (job_id, status, created_at, command, exit_code, logs_url, etc.). Return type example: {"job_id": "string", "status": "enum(pending|running|completed|failed)", "started_at": "ISO8601", "completed_at": "ISO8601", "exit_code": "integer"}
Expand joblet_run_job description to 100-150 chars explaining intent: 'Execute a job immediately with resource limits (CPU, memory, GPU). Returns job_id for polling. For deferred execution, use schedule parameter with RFC3339 timestamp. For monitoring, use joblet_get_job_status(job_id).'
Add enum constraints to joblet_run_job parameters: 'network' should be an enum (e.g., "default"|"isolated"|"vpn"), 'runtime' an enum ("python"|"node"|"bash"|...), not free-form strings.
Add range constraints to numeric parameters: max_cpu (1-100), max_memory (1-262144 for MB), gpu_count (0-8), limit (1-100). Include in parameter descriptions: 'max_cpu: Maximum CPU percentage (1-100, default 50).'
Document idempotency: Is joblet_run_job idempotent? If the same command is submitted twice, does it create one job or two? Document for agent retry safety.
Add error recovery guidance: 'If a job fails, call joblet_get_job_logs(job_id) to inspect stderr/stdout. Retryable errors: timeout (retry with longer timeout), resource_exhausted (reduce gpu_count or max_memory). Non-retryable: invalid_command (fix the command and resubmit).'
Clarify joblet_list_jobs pagination: 'Returns up to 'limit' jobs (default 20, max 100). If more jobs exist, include next_cursor in response to fetch the next batch. Always include total_count so agents know how many jobs exist.'
No error handling guidance. What happens when a job times out, exceeds resource limits, or the command fails? Should the agent retry, ask the user, or move on? Tool descriptions provide no recovery hints.
joblet_list_jobs accepts 'limit' (integer) but no minimum/maximum bounds documented. No pagination info: does it return a total_count, next_cursor, or just the first N items? If 1000 jobs exist, what happens?
Parameter descriptions are uniformly brief (10-30 chars). 'Filter by job status' and 'Job UUID (supports short form)' lack context. Why would an agent filter by status? What format should the UUID be in? The descriptions do not prompt LLM reasoning.
Expand parameter descriptions to 50-100 chars. Example: 'cpu_cores: CPU core specification as a string (e.g., "0-3" for cores 0-3, "4" for core 4 only). Requires Joblet server v5.6+.'
Document which parameters are mutually exclusive or co-dependent. E.g., 'If schedule is set, the job will not run immediately, use joblet_list_jobs with status=pending to monitor until execution. If schedule and timeout are both set, timeout is measured from scheduled start time, not submission time.'
Add tool annotation hints if present in the SDK: mark joblet_run_job as destructiveHint (side effect: creates resources), joblet_list_jobs as readOnlyHint (safe to call freely), joblet_get_job_logs as readOnlyHint.