VHGENGINE

by app.railway.up.engine-production-3bdc

wait_for_job

Read-only

Block until a job is terminal, then return it. Free, bounded, no poll loop.

    Returns the EXACT get_job body plus timed_out, waited_ms and polls, so branch on
    `status` exactly as you would with get_job. timed_out:true is NOT a failure, it
    means the budget ran out: call again with the SAME job_id. Waiting neither cancels
    nor charges; the worker charges when it runs the job either way. It returns
    IMMEDIATELY with worker_alive:false + `warning` when no worker exists here.
    Errors: unauthorized, not_found (unknown or foreign job_id), rate_limited.

Input Schema

TableJSON Schema

Name	Required	Description
`job_id`	Yes	The job to wait on, as returned by start_generate_job (or by a generate_hooks call that auto-jobbed on deadline_ms). Account-scoped: an id you do not own reads as not_found.
`api_key`	No	API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (the stdio default). No key resolvable -> unauthorized.
`timeout_seconds`	No	How long to block, 1-300 seconds. Keep it BELOW your own MCP client's request timeout, or the client gives up before this tool answers. Running out is not an error: you get timed_out:true plus the job's live state.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	On failure: the same typed error envelope a synchronous call returns. details.cancelled true means YOU cancelled it with cancel_job, not a fault.
`polls`	No	How many get_job reads this call made on your behalf.
`stage`	No	The real engine stage reached (e.g. brief, draft, judge).
`job_id`	No	The job waited on.
`result`	No	On success: the FULL generate (or batch) body, always full-verbosity. At standard/full, a judge-ranked smart hook may also carry {shape, phone_test, say_it}; a judge-ranked research hook carries receipts {persona, shape, phone_test, say_it, pattern_source}. pattern_source is null when no measured opener was attributed, otherwise its nested provenance is the authoritative actual platform, source surface, transcript method, language, route, media, and origin-time record. Minimal keeps persona and shape, plus phone_test only when it is the warning value 'fail'.
`status`	No	queued, running, succeeded (see `result`) or failed (see `error`). With timed_out:false this is always succeeded or failed unless worker_alive is false.
`warning`	No	Present only alongside worker_alive:false; says what to do instead.
`timed_out`	No	true when timeout_seconds elapsed before the job finished. NOT a failure: call wait_for_job again with the SAME job_id, or poll get_job.
`waited_ms`	No	How long this call actually blocked.
`elapsed_ms`	No	Milliseconds since the job started running.
`eta_seconds`	No	Estimated seconds still remaining.
`progress_pct`	No	0-100 progress within the run.
`worker_alive`	No	Present and FALSE only when the wait returned immediately because no job worker will ever run this job. Then read `warning`.
`hook_instances`	No	Immutable non-prose served-occurrence identities. Profile-bound queued/running work returns an empty list; a successful result returns one row per served hook.
`poll_after_seconds`	No	How long to wait before polling again; 0 once finished.
`resolved_creator_profile`	No	Exact immutable creator-profile binding used by this occurrence. Null/absent for inline or unprofiled generation.

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses crucial behavioral traits: waiting is free, bounded, does not cancel or charge, returns immediately if no worker exists, and timed_out is not a failure. It also lists error conditions (unauthorized, not_found, rate_limited), going well beyond the annotation's minimal read-only indicator.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact yet thorough, with the core purpose in the first sentence and subsequent lines providing essential caveats. Every sentence adds value, and formatting (line breaks) improves readability without unnecessary verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even with an output schema present, the description explains the exact return shape (get_job body plus timed_out, waited_ms, polls), timeout semantics, the no-worker error path, and possible errors. This leaves no major gaps for a blocking-wait tool and gives the agent everything needed for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with each parameter already well-described in the input schema. The description reinforces the timeout behavior and the job_id reuse pattern, but adds little new meaning beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description leads with a specific verb phrase 'Block until a job is terminal, then return it', clearly indicating the tool's core function. It further distinguishes itself from get_job by noting it returns the exact get_job body plus extra fields, making it distinct from a simple fetch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It establishes when to use this tool (when blocking on job completion is desired) and contrasts with get_job by sharing its output structure. The retry pattern on timeout ('call again with the SAME job_id') and the worker_alive:false edge case provide clear operational guidance, though it doesn't explicitly name alternative tools beyond get_job.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All VHGENGINE tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.1/5.0

Disambiguation5/5

Each tool targets a distinct resource and action, e.g., signup vs. delete_account, create_key vs. revoke_key, generate_hooks vs. score_hook. Even similar tools like generate_hooks and generate_hooks_batch are clearly differentiated by single vs. batch operation.

Naming Consistency5/5

All 32 tools use a consistent verb_noun snake_case pattern (e.g., add_credits, create_checkout, revoke_key, list_outcomes) with no mixing of camelCase or other conventions.

Tool Count4/5

32 tools is slightly above the typical 15-tool range, but the domain is broad (account, keys, webhooks, generation, scoring, jobs, outcomes), and each tool has a specific purpose. No tools seem redundant.

Completeness4/5

The tool surface covers most lifecycle operations: CRUD for accounts/keys/webhooks, generation/scoring with batch and async variants, outcomes reporting, and auxiliary tools. Missing explicit delete for hooks (expire automatically) and some update operations, but no critical gaps.

Resources

Need Help?