VHGENGINE

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

research_hook_evidence

Return a deterministic, unpadded portfolio of verified hook evidence. Hard evidence gates precede relevance and diversity; views are observed platform views. Openers are audio_verified, or transcript_grounded with explicit caveats when enabled. Each item has a grounded idea and later exact payoff, bound by content_arc_receipt to one request, media and transcript, with first_audible_speech and leading_segments preserving earlier speech. New calls are exact-only; retained terminals may replay legacy shapes. Where the provider runtime is bound this DISPATCHES and SPENDS credits under a 300-second authorization: allow at least 310 seconds. Errors: unauthorized, invalid_request, idempotency_conflict, rate_limited.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`depth`	No	V1 standard supports up to 5 items; deep supports up to 10.	standard
`topic`	Yes	The exact subject the evidence hooks must address.
`locale`	No	Explicit country, dialect, script, and code-switch policy.
`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.
`formats`	No	V2 allowed speaking formats. Omit for the four-format bundle.
`audience`	No	Optional intended viewer whose fit is scored from evidence.
`freshness`	No	Maximum source age: any, 7d, 30d, or 90d.	any
`must_exclude`	No	Concepts every admitted item must evidence as absent.
`must_include`	No	Exact concepts every admitted item must evidence.
`allow_partial`	No	Must be false; public evidence delivery is exact-only.
`viewer_action`	No	Optional desired viewer action scored from evidence.
`schema_version`	No	Use hook-research-request-v2 to opt into the V2 contract.	hook-research-request-v1
`desired_outcome`	No	Optional outcome that evidence must support.
`idempotency_key`	No	Caller-chosen replay key (any string, unique per intended effect). A repeat call with the SAME key returns the stored result and is NEVER charged twice; the same key with different arguments is an idempotency_conflict. Omit and every call is a fresh, separately charged operation.
`requested_count`	No	V1 maximum verified items, 1-10.
`requested_format`	No	Optional V1 format preference; omission makes format irrelevant to selection and refusal.
`problem_or_tension`	No	Optional problem or tension that evidence must match.
`requested_count_v2`	No	V2 maximum verified items, 1-30; omission defaults to 10.
`requested_language`	No	Requested output evidence language: en, fr, es, ar, or ary.	en
`source_requirements`	No	Per-platform delivery quota policy. If supplied, include TikTok, Instagram, and YouTube exactly once. Required sources use a minimum of 1-10; preferred sources must use 0.
`allowed_opener_states`	No	Opener states this caller accepts. Both public states are accepted by default; transcript_grounded items carry an explicit caveat.
`source_requirements_v2`	No	V2 per-platform quotas; omission prefers all three platforms.
`minimum_acceptable_count`	No	Legacy compatibility field. Omit to require requested_count exactly; an explicit value must equal requested_count.
`minimum_distinct_sources`	No	Minimum distinct admitted platforms, 1-3.
`accepted_source_languages`	No	Verified spoken languages eligible as sources.

Output Schema

TableJSON Schema

Name	Required	Description
`items`	No	Up to ten admitted items. New non-success responses contain none; an exact retained pre-strict insufficient terminal may preserve historical items. Each item includes the canonical URL, observed platform views, non-ad evidence, acquisition origins and call receipts, verification artifact hashes, language, format, opener state, topic-fit explanation, an explicit source_video object, an explainable non-virality score receipt, and caveats.
`status`	No	New commissions return succeeded, insufficient_verified_supply, unsupported_cell, or failed. An exact retained pre-strict terminal may reproduce deprecated degraded or an item-bearing insufficient response; replayed stays truthful for first publication after crash recovery versus a stored retry.
`replayed`	No	Whether an idempotency record supplied this response.
`operation`	No	Always research_hook_evidence.
`request_id`	No	Trace id for this call.
`cost_receipt`	No	Pricing policy plus credits_reserved, credits_charged, credits_remaining, and proof that charge did not exceed reservation.
`deficiencies`	No	Machine-readable shortfall, unsupported-cell, or execution-failure reasons.
`plan_receipt`	No	Sanitized planning receipt, support decision, and any unsupported cells.
`schema_version`	No	Frozen response contract version.
`delivered_count`	No	Verified items actually delivered, exactly matching items length.
`policy_receipts`	No	Planner, verifier, ranking, and pricing policy identifiers that governed the result.
`public_response`	No	Optional candidate evidence view. Omitted unless VHGENGINE_RESEARCH_INTELLIGENCE_PUBLIC_RESPONSE_V2 is on. Never replaces hook_text. Never includes signed media URLs.
`ranking_receipt`	No	Stable hard-gate, score, rejection, and selection receipts for every candidate.
`request_receipt`	No	Canonical request schema version and SHA-256 receipt.
`requested_count`	No	Requested portfolio size, 1-10.
`replayed_at_charge`	No	Whether replay was detected inside the atomic commit boundary.
`acquisition_receipt`	No	Immutable acquisition plan, call, budget, source-settlement, and deficiency receipt.
`minimum_acceptable_count`	No	Minimum count the caller declared useful.
`distinct_source_settlement`	No	Requested and delivered source diversity plus its met flag.
`required_source_settlement`	No	Per-platform policy, required minimum or preferred zero, delivered count, and met flag.

TDQS

A3.6/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and does so exceptionally well. It discloses that the operation can DISPATCH and SPEND credits under a 300-second authorization, requires at least 310 seconds, returns deterministic unpadded results, enforces hard evidence gates, and lists specific error types. This is far beyond a generic research-tool description.

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

Conciseness3/5

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

The description is compact and front-loaded with the most important statement, but it is a dense wall of jargon ('content_arc_receipt', 'retained terminals may replay legacy shapes') that would benefit from clearer structure or a short glossary. Every clause carries information, but the delivery is hard to parse quickly.

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

Completeness4/5

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

For a high-complexity tool with 25 parameters and a rich schema plus output schema, the description covers the operational essentials that structured fields cannot: credit spending, timeout expectations, exact-only delivery, deterministic behavior, and error cases. It is not fully complete because it omits selection guidance versus siblings, but for invocation it is largely sufficient.

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 description coverage is 100% for all 25 parameters, so the schema carries the parameter-level burden and the baseline is 3. The description references domain concepts like content_arc_receipt and leading_segments, but these do not map cleanly to individual parameters, and it adds little parameter-specific meaning beyond what the schema already provides.

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

Purpose4/5

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

The description opens with a concrete action: 'Return a deterministic, unpadded portfolio of verified hook evidence,' giving the agent a clear verb and resource. It does not explicitly differentiate from sibling tools like generate_hooks or synthesize_hooks, and several domain terms are opaque, but the core purpose is understandable.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus alternatives such as generate_hooks, synthesize_hooks, or score_hook. The description states policies like 'New calls are exact-only' but never tells an agent under what conditions to select this tool, which is a significant gap given the large sibling 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?