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).

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

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?