VHGENGINE

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

get_usage

Read-only

Return the credit balance, per-operation totals, and recent ledger. Free.

    Args: recent_limit (1-200, default 50), offset (>=0, pages `recent` past the newest
    rows), request_id (scope recent to that call's charges), tag + key_prefix (WP-J
    fleet filters), api_key. Returns {credits, totals:{by_operation}, recent:[...]}
    (each row carries key_prefix; tags in metadata).
    Errors: unauthorized, invalid_request, rate_limited.

Input Schema

TableJSON Schema

Name	Required	Description
`tag`	No	Filter to rows carrying EXACTLY this fleet tag (exact match, not a substring). Omit for every tag.
`offset`	No	Rows to skip before `recent` starts, for paging past the newest page. Page with offset += recent_limit, exactly like list_hooks and list_outcomes; an offset past the end is an empty `recent`, never an error. `totals` always covers all history and is never paged away. For the WHOLE ledger in one call use export_usage instead.
`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.
`key_prefix`	No	Filter to charges made with ONE api key, identified by the 12-char prefix from list_keys (e.g. vhg_sk_ab12). Omit for every key.
`request_id`	No	Scope `recent` to the charges of ONE earlier call: pass the request_id that call RETURNED (or its X-Request-Id header), never a freshly minted id. An id that charged nothing matches no rows and comes back as an empty `recent`, not an error. Omit for all recent charges.
`recent_limit`	No	Max recent ledger rows to return, 1-200. Totals are unaffected by this; it only sizes `recent`.

Output Schema

TableJSON Schema

Name	Required	Description
`recent`	No	Recent charge rows, newest first, sized by recent_limit. Each carries the operation, credits, key_prefix, request_id and tags in metadata.
`totals`	No	{by_operation: {op: {calls, credits}}} over the whole account lifetime.
`credits`	No	Current balance.
`unreported_hooks`	No	How many bought hooks still have no outcome, i.e. how much free reward is on the table. Find them with list_hooks(unreported=true).

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedAug 2, 2026

addedInput schema / properties / api_key / description

Added value: +"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."

addedInput schema / properties / key_prefix / description

Added value: +"Filter to charges made with ONE api key, identified by the 12-char prefix from list_keys (e.g. vhg_sk_ab12). Omit for every key."

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Rows to skip before `recent` starts, for paging past the newest page. Page with offset += recent_limit, exactly like list_hooks and list_outcomes; an offset past the end is an empty `recent`, never an error. `totals` always covers all history and is never paged away. For the WHOLE ledger in one call use export_usage instead.",
+  "maximum": 9223372036854776000,
+  "minimum": 0,
+  "title": "Offset",
+  "type": "integer"
+}

addedInput schema / properties / recent_limit / description

Added value: +"Max recent ledger rows to return, 1-200. Totals are unaffected by this; it only sizes `recent`."

addedInput schema / properties / recent_limit / maximum
```
Added value: +200
```
addedInput schema / properties / recent_limit / minimum
```
Added value: +1
```

addedInput schema / properties / request_id / description

Added value: +"Scope `recent` to the charges of ONE earlier call: pass the request_id that call RETURNED (or its X-Request-Id header), never a freshly minted id. An id that charged nothing matches no rows and comes back as an empty `recent`, not an error. Omit for all recent charges."

addedInput schema / properties / tag / description

Added value: +"Filter to rows carrying EXACTLY this fleet tag (exact match, not a substring). Omit for every tag."

addedOutput schema / description

Added value: +"Balance, per-operation totals, and the recent charge ledger."

addedOutput schema / properties

Added value: +{
+  "credits": {
+    "description": "Current balance.",
+    "type": [
+      "number",
+      "null"
+    ]
+  },
+  "recent": {
+    "description": "Recent charge rows, newest first, sized by recent_limit. Each carries the operation, credits, key_prefix, request_id and tags in metadata.",
+    "type": [
+      "array",
+      "null"
+    ]
+  },
+  "totals": {
+    "description": "{by_operation: {op: {calls, credits}}} over the whole account lifetime.",
+    "type": [
+      "object",
+      "null"
+    ]
+  },
+  "unreported_hooks": {
+    "description": "How many bought hooks still have no outcome, i.e. how much free reward is on the table. Find them with list_hooks(unreported=true).",
+    "type": [
+      "object",
+      "null"
+    ]
+  }
+}

removedOutput schema / title
```
Removed value: -"get_usageDictOutput"
```

Changed1 schema field changedJul 20, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
First observedJul 18, 2026

TDQS

A4.1/5.0

Behavior4/5

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

The annotation readOnlyHint=true already signals a safe read operation. The description adds value with error types (unauthorized, invalid_request, rate_limited), a 'Free' cost note, and a clear return shape including legacy metadata. It does not contradict annotations and provides additional behavioral context beyond the safety flag.

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 and well-structured: first the one-sentence purpose, then a parameter summary, return shape, and errors. Each line earns its place and there is no repetition of schema fields. The formatting with line breaks aids scannability.

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?

With an output schema present and readOnly annotation, the description is comprehensive: it covers scope, defaults, pagination hints, error conditions, and free usage. It even notes what each row carries. For a 6-param read-only tool, this leaves no critical gaps evident.

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%, so the schema already documents all six parameters precisely. The description's condensed parameter list (e.g., 'tag + key_prefix (WP-J fleet filters)') adds mild conceptual grouping but no new syntax or semantics. This meets the baseline expected when schema handles param detail.

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 ('Return') and three concrete resources (credit balance, per-operation totals, recent ledger), making the tool's function unambiguous. It distinguishes itself from siblings by scoping to 'recent ledger' rather than whole-history exports (export_usage), even without naming alternatives.

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

Usage Guidelines3/5

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

The description lacks an explicit statement of when to select this tool over related tools like export_usage or get_account. It implies usage by enumerating return values and mentioning 'Free,' but does not provide exclusions or alternatives. Thus it is adequate but not a strong usage guide.

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?