VHGENGINE

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

get_job

Read-only

Poll an async job: status, real engine stage, progress, ETA, result/error.

    Poll after poll_after_seconds until status is "succeeded" (result holds the full
    generate body) or "failed" (error holds the typed envelope). Only the owning
    account can read a job; a foreign/unknown id is not_found (no existence leak).
    Returns {job_id, status, stage, progress_pct, eta_seconds, elapsed_ms,
    poll_after_seconds, result, error}. Errors: unauthorized, not_found, rate_limited.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`job_id`	Yes	The job's id, 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.

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.
`stage`	No	The real engine stage while running (e.g. brief, draft, judge).
`job_id`	No	The job polled.
`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 (waiting on a worker), running, recovery_required (a hook-research V2 job fenced on ambiguous vendor settlement; operator recovery owns it), succeeded (see `result`), failed (see `error`). Stop polling on the last two.
`elapsed_ms`	No	Milliseconds since the job started running.
`eta_seconds`	No	Estimated seconds remaining.
`progress_pct`	No	0-100 progress within the run.
`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.
`resolved_creator_profile`	No	Exact immutable creator-profile binding used by this occurrence. Null/absent for inline or unprofiled generation.

TDQS

A4.4/5.0

Behavior5/5

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

The description enriches the readOnlyHint annotation by disclosing the polling loop, the success/failure envelope semantics, the no-existence-leak privacy behavior, and the error list (unauthorized, not_found, rate_limited). This goes well beyond the annotation and gives the agent a clear model of what the call observes and how it behaves.

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

Conciseness4/5

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

The description is front-loaded with purpose and then provides dense, useful guidance on polling, ownership, return fields, and errors. The 'Returns {...}' sentence is slightly redundant given the output schema exists, but it is compact and does not make the description bloated.

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?

For a read-only polling tool with strong schema and output-schema coverage, the description is complete: it explains the polling cadence, terminal states, result/error contents, account scoping, and error cases. Nothing important is left ambiguous for an agent invoking this tool.

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?

The input schema already provides 100% descriptive coverage for both job_id and api_key, including account scoping and header fallback behavior. The description adds no parameter-specific detail beyond what the schema states, so the baseline of 3 is appropriate.

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 opens with a specific verb and resource: 'Poll an async job', and lists the concrete status/progress fields it returns. It is clearly distinct from sibling tools like list_jobs, wait_for_job, and cancel_job because it explicitly frames this as a single-job polling read, not a list, block, or mutation.

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?

The description gives clear when-to-use guidance: 'Poll after poll_after_seconds until status is "succeeded"... or "failed"', which precisely tells the agent how to consume the tool. It also adds ownership and not_found behavior, but it does not explicitly name alternatives like wait_for_job for blocking use cases, so it stops short of a full when-not/exclusion list.

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?