Platform Tools

Hypervize provides several built-in platform tools that your agents can use without you writing any code. These tools are executed server-side by Hypervize (not your client or backend).

When you enable a platform tool:

• It is automatically available on inference requests for your account.
• The model can call it naturally.
• We run the tool and continue the model turn for you (streaming).
• Usage is billed separately from tokens as a tool call.

How to Enable Platform Tools

1. Go to the Alexandria page in the dashboard.
2. Toggle the tools you want (Athena, Vesper, Herald, Pandora, Iris, Ledger, and Chronos are available).
3. Or use the API:
   HTTP

   COPY

   POST /api/tools
   { "tool_id": "ledger" }

Tools are per-user (tied to your Hypervize account). Once enabled they are available everywhere you use your keys (Chat, API, MCP, and Chronos recipes).

Tool discovery (OpenClaw / agents)

Auth: Authorization: Bearer <api_key> (or dashboard session).

List enabled tools

GET /api/tools

{
  "user_enabled_tools": [{ "tool_id": "vesper" }, { "tool_id": "athena" }],
  "tools": [
    {
      "name": "vesper",
      "description": "…",
      "enabled": true,
      "detail_url": "/api/tools/vesper"
    }
  ]
}

Tool detail (schema + samples)

GET /api/tools/{toolName}

Example: GET /api/tools/vesper

Returns (among other fields):

Unknown names → 404. Not enabled → still returns schema with "enabled": false.

To schedule tool (and model) sequences on a cron, see Chronos — same API key as inference, with full JavaScript examples for programmatic jobs.

Note: Prefer "stream": true for platform tools (server-managed multi-turn over SSE). Non-stream is supported: we run the managed loop server-side and return one aggregated chat.completion JSON.

Athena — Foundational Intelligence

What it does
The essential "brain" add-on. Provides real-time time/date awareness and safe basic calculations so agents don't hallucinate numbers or dates.

Parameters

• expression (optional string): Arithmetic expression to evaluate (e.g. (2 + 3) * 4). Omit for current time (returns ISO 8601).

Examples

• "What time is it?" → calls Athena with no expression.
• "Calculate (42 + 17) * 3" → calls with expression: "(42 + 17) * 3"

Pricing
$0.00075 per call.

When to use
Always enable this one. It grounds every agent.

Vesper — Web Intelligence

What it does
Full internet access for agents. Search the live web with screenshots, or fetch any page and extract what you need.

Supports natural language instructions for precise extraction and multiple output formats.

Parameters

• query (string, for search): What to search for.
• url (string): Specific page to fetch.
• num_results (number, optional): Max results for search (default 5).
• instructions (string, optional): Natural language guidance, e.g. "Extract all pricing tiers as a JSON array".
• output_format ("text" | "markdown" | "json", optional): Default "markdown".
• selectors (object, optional): Advanced CSS selectors for targeted extraction.
• include_metadata (boolean, optional): Include title, structured data, Open Graph, etc. Default true.

How it works
Search returns ranked results with screenshots. URL mode fetches a page and extracts content (including tables, headings, links, and metadata). Steer extraction with natural-language instructions and optional CSS selectors.

Examples

• "Latest AI model benchmarks" (uses query)
• Fetch a competitor pricing page + instructions: "return all plans and prices as structured JSON"

Pricing
$0.015 per call.

When to use
Any research, fact-checking, monitoring, or data gathering task.

Herald — Direct Agent Voice

What it does
Send emails from your agents to any address. Supports plain text, Markdown, or raw HTML.

Permission rule
Herald may only send mail when you have explicitly asked in the conversation (e.g. "email me this", "send that to …", "yes, send it"). Agents may offer to email results, but must wait for clear affirmative permission. They must not email proactively after finishing a task or "to be helpful." Completing research or finishing a summary is not permission.

Parameters

• body (string, required): Content (markdown or HTML).
• subject (string, optional): Default "Update from your Hypervize agent".
• to (string, optional): Any email address. Defaults to your account's primary email.
• format ("text" | "html", optional): Default "text". When "html", Markdown is auto-converted.
• attachment_file_id (string, optional): A Library file id from Ledger (file_id=… in the Ledger result). Attaches that file to the email when allowed.

Limits

• Body ≤ 10,000 characters
• Subject ≤ 200 characters
• 20 emails per user per hour
• Attachments must be files from your Library (via Ledger); size limits apply

Examples (user must ask)

• "Email me the latest competitor pricing table"
• "Send a nicely formatted daily summary"
• "Create a PDF of this brief with Ledger, then email it to me with the file attached"
• Agent: "Want me to email this summary?" → User: "Yes, send it" → then Herald may run

Pricing
$0.05 per call.

When to use
When you want the agent to notify you or deliver results on request (and inside Chronos schedules where delivery is the scheduled job itself). Pair with Ledger when the result should be a real file attachment, not only email body text.

Pandora — Google Workspace

What it does
Read and write across Google services for agents: Drive, Docs, Sheets, Gmail, and Calendar. Supports connecting your own account or an external user’s Google account.

Common capabilities (tool names the model can call after enablement)

• Connect: pandora_initiate_connection (full Drive / Docs / Sheets / Slides / Calendar write scopes — re-auth after scope changes)
• Drive / files: pandora_list_drive_files
• Gmail: pandora_search_gmail, pandora_get_gmail_message, pandora_draft_email
• Docs: pandora_create_google_doc, pandora_get_google_doc, pandora_update_google_doc
• Sheets: pandora_create_google_sheet (optional initial values), pandora_write_google_sheet
• Slides: pandora_create_google_slides — designed decks (theme + slides[] with kind title|section|bullets|quote|closing)
• Calendar: pandora_list_calendar_events, pandora_create_calendar_event (attendees → invites)

How it works
Enable Pandora in Alexandria, complete Google OAuth when prompted, then the granular tools above are available to the model. Chronos recipes often chain Pandora tools with a model step and Herald for digests.

Pricing
$0.015 per call (each Pandora tool invocation).

When to use
Inbox digests, calendar briefings, drafting mail, or creating docs/sheets from agent work.

Iris — Image Creation

What it does
Generate images from a text description. Hypervize selects an image model (quality vs speed) and returns the result. Agents must call Iris for new pictures — they should not invent image URLs.

Parameters

• prompt (string, required): Detailed image description (subject, style, lighting, composition).
• quality ("auto" | "fast" | "high", optional): Default "auto" (Hypervize picks); fast or high force a tier.

Examples

• "Generate a minimalist logo for a coffee brand, flat vector, cream and charcoal"
• "Poster for a summer concert, bold type, sunset gradient"

Pricing
$0.015 per call.

When to use
Any request for a new illustration, icon, poster, or photo-style image.

Ledger — Files & Data

What it does
Create, read, and convert real files your agent can hand off: CSV, JSON, Markdown, plain text, HTML, and PDF. Files appear in Chat → Library → Files, where you can download them while signed in. Use Herald with attachment_file_id to email a file as an attachment.

Ledger is for artifacts (spreadsheets, reports, exports)—not for inventing download links in plain text.

How to enable

POST /api/tools
Authorization: Bearer $HVZ_KEY
Content-Type: application/json

{ "tool_id": "ledger" }

Or toggle Ledger on Alexandria or in Chat tools.

Parameters (tool name: ledger)

At least one of content or rows is required for create/convert (unless you only pass what that format needs). read needs file_id or content.

What you get back
A short status string that includes:

• file_id=… — use this with Herald attachment_file_id, or to read the file later
• url=… / download path — open while signed into Hypervize (Library Files tab works the same way)
• format, filename, and size

Suggested recipes

1. Table → CSV
   “Turn this list of leads into a CSV with columns name, email, company” → Ledger create + format=csv + rows=[…].

2. Research → PDF
   Vesper (or your own content) → Ledger create + format=pdf + content = full HTML the model designs (headings, sections, lists)—same idea as Herald HTML email body.

3. File → email
   Ledger create → Herald with a short body and attachment_file_id set to the Ledger file_id (user must ask to email, or use a Chronos job that includes both steps).

4. Google data → file
   Pandora (Drive/Sheets/Gmail context) → model shapes the data → Ledger creates CSV or PDF → optional Herald.

5. Scheduled digest (Chronos)
   Same tools in a recipe: gather with Pandora/Vesper → optional model step → Ledger PDF/CSV → Herald email. Chronos only replays the tools you already use in Chat—no special Ledger mode.

Chat / natural language examples

• “Export these rows as a CSV I can download.”
• “Make a PDF of this daily brief and put it in my library.”
• “Convert that CSV into pretty JSON.”
• “Read file_id … and summarize the first rows.”
• “Create the PDF, then email it to me with the file attached.”

API usage
Enable Ledger, then call chat completions with streaming as usual (with no plain tools in the body, enabled platform tools are available to the model). The model will call ledger when the task needs a file. You can also invoke tools explicitly via your agent framework’s tool loop against Hypervize (same schemas as other platform tools). To combine platform tools with your own plain function schemas on one request, see Using plain tools with platform tools.

Minimal streaming request (platform tools available when enabled for the key and you do not send plain client tools):

curl -N https://hypervize.tech/api/chat/completions \
  -H "Authorization: Bearer $HVZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-3",
    "stream": true,
    "messages": [{
      "role": "user",
      "content": "Create a CSV of three sample cities with columns city and country, save it with Ledger, and tell me the file_id."
    }]
  }'

Direct tool execute (when you already know the arguments):

curl https://hypervize.tech/api/tools/execute \
  -H "Authorization: Bearer $HVZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ledger",
    "arguments": {
      "action": "create",
      "format": "csv",
      "filename": "cities.csv",
      "rows": "[{\"city\":\"Nashville\",\"country\":\"US\"},{\"city\":\"Austin\",\"country\":\"US\"}]"
    }
  }'

Then email the file (user permission still applies in Chat):

curl https://hypervize.tech/api/tools/execute \
  -H "Authorization: Bearer $HVZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "herald",
    "arguments": {
      "subject": "Your export",
      "body": "Attached is the file you requested.",
      "format": "text",
      "attachment_file_id": "PASTE_FILE_ID_FROM_CODEX"
    }
  }'

Library
Open Chat → Library → Files to browse and download Ledger outputs while signed in.

Limits (product)

• Practical size caps for create/read (large bulk dumps may be rejected; split work if needed).
• Not available on free-message tool sets (paid tool usage).
• Streaming inference required for automatic tool use on chat completions.

Pricing
$0.03 per successful Ledger call.

When to use
Anytime the user needs a downloadable or attachable file—reports, exports, tables, PDFs—not just chat text. Prefer Ledger over pasting huge CSV/PDF content into the model reply.

Chronos — Scheduled Recipes

Enable Chronos in Alexandria or Chat tools (same toggle store as other products). When on:

• Chat: Schedule appears on assistant replies that used tools → Library → Scheduled tasks
• API: POST /api/chronos/jobs with your Hypervize API key works

Chronos is not injected as a model function — it gates scheduling only. You define ordered tool and optional model steps; Chronos replays them on a schedule.

Pricing: $0.01 per run + each tool step + any model tokens.

Full guide: Chronos.

Billing & Observability

All platform tool calls are recorded as tool usage (separate from token usage).

• Visible in dashboard usage pages.
• Billed from your prepaid balance — including when the model runs on a dedicated endpoint.
• Dedicated weekly invoices cover GPU capacity only; they never include tool charges.
• Usage details can include tool-specific context (e.g. recipient for Herald, query for Vesper).

See Billing & Payments → Tool Calls for dual billing and the dedicated low-balance guard.

Best Practices

• Enable Athena for almost every use case.
• Combine Vesper + Herald for "research then notify me" flows.
• Use Ledger when the deliverable is a file (CSV/PDF); use Herald body alone only for short notes.
• Ledger → Herald (attachment_file_id) for “email me the file.”
• Use Pandora + Ledger + Chronos for recurring “pull data → file → email” jobs.
• Use instructions and output_format: "json" with Vesper for structured data your agent can parse reliably.
• Keep rate limits in mind for Herald (20/hr is generous for most agents).
• For Iris, always show the URL returned by the tool — never invent image links.
• For Ledger, use the returned file_id and Library download—don’t invent file links.

More tools

We plan to add more platform tools. Watch the Alexandria page for new toggles.

Related

• Tool Calling — webhooks + plain schemas
• Chronos — scheduled recipes (including Ledger + Herald patterns)
• Billing & Payments
• Errors & Troubleshooting

These tools are available automatically when enabled. Your agents will discover and use them through normal tool calling.