VHGENGINE

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

synthesize_hooks

Write original hooks derived from verified viral source evidence. Each hook cites one admitted source: verbatim opening, timestamps or explicit nulls for untimed transcript evidence, observed views with observation time and a versioned virality receipt whose caveats say views correlate with, not prove, quality. A lexical novelty guard rejects copied source wording; quality stays unmeasured; never padded. idempotency_key is REQUIRED; a replay returns the exact stored terminal, uncharged. Live posture: GET /health hook_synthesis_enabled; evidence and LLM gates also apply. Errors: unauthorized, invalid_request, idempotency_conflict, conflict, rate_limited.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`depth`	No	standard supports up to 5 hooks; deep supports up to 10.	standard
`topic`	Yes	The exact subject the original 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.
`audience`	No	Optional intended viewer the hooks are written for.
`freshness`	No	Maximum source age: any, 7d, 30d, or 90d.	any
`must_exclude`	No	Concepts every admitted source must evidence as absent.
`must_include`	No	Exact concepts every admitted source must evidence.
`viewer_action`	No	Optional desired viewer action.
`desired_outcome`	No	Optional outcome the video promises.
`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	Original hooks to write, 1-10; one per distinct source.
`requested_format`	Yes	The single speaking format the hooks are written in. It instructs the writer and does not filter the sources: this build cannot verify a format on a source.
`problem_or_tension`	No	Optional problem or tension the hooks should open.
`requested_language`	No	Requested language: en, fr, es, ar, or ary.	en
`allowed_opener_states`	No	Opener states this caller accepts. Both public states are accepted by default; transcript_grounded sources carry an explicit caveat.
`source_requirements_v2`	No	Per-platform source quotas; omission prefers all three.
`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
`hooks`	No	One entry per original hook: hook_text, format, mechanism (verified facts plus grounded description), source_evidence (verbatim opening, timestamps, observed views with observation time, versioned virality receipt), transformation (source_mechanism, adaptation, passed novelty_guard), confidence (structural basis, quality unmeasured), caveats.
`status`	No	succeeded (exact count), partial (fewer, with the deficiency stated), insufficient_evidence, capability_unavailable (this deployment's closed default), or failed. Non-delivery statuses charge nothing.
`replayed`	No	true when an idempotency_key replayed a stored result, so nothing was charged again. The credits_charged below is what the ORIGINAL call cost.
`request_id`	No	The commission id, echoed on replay.
`cost_receipt`	No	Reservation and charge; the charge never exceeds the reservation.
`deficiencies`	No	Why anything fell short, per source where attributable. Codes include hook_synthesis_disabled, evidence_capability_unavailable, llm_transport_unconfigured, novelty_guard_rejected, llm_unavailable.
`quality_claim`	No	Always 'unmeasured' until a measurement instrument ships.
`delivered_count`	No	Number of delivered hooks; never padded.
`requested_count`	No	The requested hook count, at most 10.
`evidence_receipt`	No	The evidence stage's state: delivered, insufficient, not_dispatched, or failed, with the delivered source count and passthrough deficiencies.
`replayed_at_charge`	No	true when the replay was detected at the charge boundary rather than up front; either way you are billed exactly once.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 18, 2026

changedInput schema / properties / requested_format / description

Previous value: -"The single speaking format for both sources and hooks."New value: +"The single speaking format the hooks are written in. It instructs the writer and does not filter the sources: this build cannot verify a format on a source."

Changed12 schema fields changedSep 2, 2026
- changedOutput schema / properties / hooks / description
```
Previous value: -"One entry per original hook: hook_text, format, mechanism (verified facts plus grounded description), source_evidence (verbatim opening, timestamps, observed views with observation time, known-non-ad proof, versioned virality receipt), transformation (source_mechanism, adaptation, passed novelty_guard), confidence (structural basis, quality unmeasured), caveats."New value: +"One entry per original hook: hook_text, format, mechanism (verified facts plus grounded description), source_evidence (verbatim opening, timestamps, observed views with observation time, versioned virality receipt), transformation (source_mechanism, adaptation, passed novelty_guard), confidence (structural basis, quality unmeasured), caveats."
```
- addedOutput schema / x-vhgengine-strict-output-schema / $defs / ResearchOpenerState
```
Added value: +{
+  "enum": [
+    "audio_verified",
+    "transcript_grounded"
+  ],
+  "title": "ResearchOpenerState",
+  "type": "string"
+}
```
- removedOutput schema / x-vhgengine-strict-output-schema / $defs / SynthesisSourceEvidence / properties / non_ad_evidence / default
```
Removed value: -null
```
- addedOutput schema / x-vhgengine-strict-output-schema / $defs / SynthesisSourceEvidence / properties / opener_end_ms / anyOf
```
Added value: +[
+  {
+    "minimum": 1,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedOutput schema / x-vhgengine-strict-output-schema / $defs / SynthesisSourceEvidence / properties / opener_end_ms / minimum
```
Removed value: -1
```
- removedOutput schema / x-vhgengine-strict-output-schema / $defs / SynthesisSourceEvidence / properties / opener_end_ms / type
```
Removed value: -"integer"
```
- addedOutput schema / x-vhgengine-strict-output-schema / $defs / SynthesisSourceEvidence / properties / opener_start_ms / anyOf
```
Added value: +[
+  {
+    "minimum": 0,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]
```
- removedOutput schema / x-vhgengine-strict-output-schema / $defs / SynthesisSourceEvidence / properties / opener_start_ms / minimum
```
Removed value: -0
```
- removedOutput schema / x-vhgengine-strict-output-schema / $defs / SynthesisSourceEvidence / properties / opener_start_ms / type
```
Removed value: -"integer"
```
- addedOutput schema / x-vhgengine-strict-output-schema / $defs / SynthesisSourceEvidence / properties / opener_verification_state / $ref
```
Added value: +"#/$defs/ResearchOpenerState"
```
- removedOutput schema / x-vhgengine-strict-output-schema / $defs / SynthesisSourceEvidence / properties / opener_verification_state / title
```
Removed value: -"Opener Verification State"
```
- removedOutput schema / x-vhgengine-strict-output-schema / $defs / SynthesisSourceEvidence / properties / opener_verification_state / type
```
Removed value: -"string"
```

Changed1 schema field changedAug 31, 2026

changedInput schema / properties / allowed_opener_states / description

Previous value: -"Sources use audio_verified by default and may use transcript_grounded with explicit caveats when the transcript flag is on."New value: +"Opener states this caller accepts. Both public states are accepted by default; transcript_grounded sources carry an explicit caveat."

Changed5 schema fields changedAug 30, 2026

changedInput schema / properties / allowed_opener_states / anyOf

Previous value: -[
-  {
-    "items": {
-      "const": "audio_verified",
-      "type": "string"
-    },
-    "maxItems": 1,
-    "minItems": 1,
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "enum": [
+        "audio_verified",
+        "transcript_grounded"
+      ],
+      "type": "string"
+    },
+    "maxItems": 2,
+    "minItems": 1,
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / allowed_opener_states / description

Previous value: -"Sources are restricted to independently audio-verified exact openers."New value: +"Sources use audio_verified by default and may use transcript_grounded with explicit caveats when the transcript flag is on."

removedInput schema / properties / allowed_opener_states / items / const
```
Removed value: -"audio_verified"
```
addedInput schema / properties / allowed_opener_states / items / enum
```
Added value: +[
+  "audio_verified",
+  "transcript_grounded"
+]
```
changedInput schema / properties / allowed_opener_states / maxItems
```
Previous value: -1New value: +2
```

Changed2 schema fields changedAug 30, 2026

addedOutput schema / x-vhgengine-strict-output-schema / $defs / SynthesisSourceEvidence / properties / non_ad_evidence / default
```
Added value: +null
```

changedOutput schema / x-vhgengine-strict-output-schema / $defs / SynthesisSourceEvidence / required

Previous value: -[
-  "candidate_id",
-  "direct_canonical_url",
-  "actual_platform",
-  "creator",
-  "observed_platform_views",
-  "views_observed_at",
-  "views_source_path",
-  "non_ad_evidence",
-  "opening_line",
-  "opener_start_ms",
-  "opener_end_ms",
-  "opener_verification_state",
-  "virality"
-]New value: +[
+  "candidate_id",
+  "direct_canonical_url",
+  "actual_platform",
+  "creator",
+  "observed_platform_views",
+  "views_observed_at",
+  "views_source_path",
+  "opening_line",
+  "opener_start_ms",
+  "opener_end_ms",
+  "opener_verification_state",
+  "virality"
+]

AddedAug 21, 2026

TDQS

A3.7/5.0

Behavior4/5

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses idempotent replay is uncharged, a lexical novelty guard rejects copied wording, quality is unmeasured, output is never padded, a live health gate exists, and enumerates possible errors. It is not exhaustive on auth or rate limits, which keeps it from a 5.

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 dense but every sentence earns its place, and the core purpose is front-loaded in the first sentence. It efficiently packs in evidence requirements, novelty enforcement, idempotency behavior, live gating, and error taxonomy without padding.

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 19-parameter tool with an output schema, the description covers operational essentials: evidence provenance, replay behavior, live posture, gates, and error cases. It is not fully complete because it omits usage routing among siblings and contains the idempotency_key contradiction, but it is otherwise quite thorough.

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

Parameters2/5

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

Schema coverage is 100%, so the baseline is 3, but the description actively muddies idempotency_key by declaring it 'REQUIRED' while the schema marks it nullable with a default of null and explicitly permits omission. The description otherwise adds little beyond schema text, which already documents replay semantics and one-per-distinct-source.

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-resource pair: 'Write original hooks derived from verified viral source evidence.' This clearly differentiates the tool from generic siblings like generate_hooks or generate_hooks_batch by foregrounding evidence-grounded originality and per-hook source citation.

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?

The description provides no explicit direction on when to use synthesize_hooks versus sibling tools such as generate_hooks, generate_hooks_batch, or remix_hook. It implies an evidence-based use case through 'derived from verified viral source evidence,' but it never states conditions, exclusions, or alternatives.

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

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?