Tool Reference
The server exposes 38 tools, grouped below by area, plus 3 resources and 3
prompts. Every tool that calls the cloud API or desktop backend converts API
and auth errors into a structured {"ok": false, "error": "..."} result
instead of failing the tool call.
Safety annotations. Tools marked read-only carry
readOnlyHint: true — they never modify anything. Tools marked
destructive carry destructiveHint: true and should be confirmed with the
user before calling. The remaining tools perform writes but are not
destructive; of these, submit_run, create_workflow, get_upload_url,
chat_with_bionodulo_ai, create_collab_invite, invite_team_member, and
desktop_submit_run are non-idempotent (idempotentHint: false), while
update_workflow and desktop_validate_workflow are idempotent.
Account
| Tool | Description | Notes |
|---|---|---|
get_account_info | Get the signed-in BioNodulo user’s account info: id, name, email and current team (id + name). | read-only |
get_service_health | Check the BioNodulo cloud service health (public endpoint, no auth). | read-only |
Billing & Credits
| Tool | Description | Notes |
|---|---|---|
get_credit_balance | Get the team’s credit balance and plan — monthlyCredits, usedCredits, remaining, percentUsed, plan name, and the AI paper-analysis quota (aiAnalysisQuota/aiAnalysisUsed). | read-only |
get_credit_usage | Get the team’s detailed credit usage / consumption ledger. | read-only |
get_usage_analytics | Get dashboard usage analytics (credit consumption over time). days is the lookback window: one of 7, 30, 90 or 180 (default 30). | read-only |
estimate_run_cost | Estimate the credit cost of a cloud run for a given compute size (vcpu, ram_gb). | read-only |
list_invoices | List the team’s billing invoices (Stripe top-ups and subscriptions). | read-only |
Runs (cloud)
| Tool | Description | Notes |
|---|---|---|
list_runs | List the team’s recent workflow runs (up to 50, newest first): id, status (queued / running / completed / failed / cancelled / interrupted), workflow id, timestamps, credits used. | read-only |
get_run_status | Get a run’s current status snapshot: id, status, recent logs, errorMessage (if failed), outputLocation, durationMs, creditsUsed, createdAt, completedAt. | read-only |
get_run_events | Get the durable event ledger for a run (lifecycle and node events). | read-only |
get_run_outputs | List the output files produced by a run (with download locations). | read-only |
submit_run | Submit a workflow for cloud execution. Consumes credits. Returns {runId, status: "queued"} — poll with get_run_status. Takes a workflow_id, an optional resource_profile (one of micro, small, medium, large, gpu, xlarge, extreme) or a custom vcpu + ram_gb pair (which must be provided together), plus optional parameters and inputs overrides. | consumes credits; non-idempotent |
cancel_run | Cancel a queued or running cloud run. | destructive |
Workflows
| Tool | Description | Notes |
|---|---|---|
list_workflows | List the team’s saved workflows (id, name, description, updated time). | read-only |
get_workflow | Get a saved workflow, including its node-graph definition. | read-only |
create_workflow | Create a new workflow in the team’s workspace, with optional description and node-graph definition ({nodes: [...], edges: [...]}). | write; non-idempotent |
update_workflow | Update a workflow’s name, description and/or node-graph definition. At least one field must be provided. | write; idempotent |
delete_workflow | Delete a workflow. This cannot be undone. | destructive |
Files
| Tool | Description | Notes |
|---|---|---|
list_files | List the team’s files — uploads and run outputs — with download URLs (up to 2000 files with presigned GET URLs). | read-only |
get_upload_url | Get a presigned URL to upload a file to the team’s storage (filename, optional content_type, default application/octet-stream). | write; non-idempotent |
delete_file | Delete a file from the team’s storage. | destructive |
Hosted AI
| Tool | Description | Notes |
|---|---|---|
get_ai_analysis | Get the status/result of an AI paper analysis (paper → workflow). Analyses are started from the website’s /build DOI flow. Provide exactly one of analysis_id or doi. | read-only |
chat_with_bionodulo_ai | Send a chat message to the hosted BioNodulo AI (OpenAI-compatible). Free for signed-in users subject to a global daily quota. Optional system_prompt; model defaults to bionodulo-ai. | write; non-idempotent |
Collab & Team
| Tool | Description | Notes |
|---|---|---|
list_collab_invites | List share-link invites for a workflow. | read-only |
create_collab_invite | Create a share link (bni_ token) for a workflow. role is viewer (default) or editor. | write; non-idempotent |
revoke_collab_invite | Revoke a workflow share-link invite. | destructive |
invite_team_member | Invite someone to the team by email (sends a Clerk organization invite). | write; non-idempotent |
Desktop App (local)
These tools talk to a locally running BioNodulo desktop app (default
http://127.0.0.1:8765) and are disabled entirely with BIONODULO_DESKTOP=0.
Unlike the cloud tools, they are marked openWorldHint: false.
| Tool | Description | Notes |
|---|---|---|
desktop_status | Check whether a local BioNodulo desktop app is running and reachable. | read-only |
desktop_list_node_types | List node types available in the desktop app’s registry (~975 nodes). Optional case-insensitive substring search filter. | read-only |
desktop_get_node_info | Get full metadata for one node type (inputs, outputs, parameters), e.g. AlphaFoldDBNode or AIDataExtractionNode. | read-only |
desktop_list_templates | List the desktop app’s built-in workflow templates (23 templates). | read-only |
desktop_validate_workflow | Validate a workflow definition locally (structure + environment readiness). | idempotent |
desktop_submit_run | Submit a workflow to the local desktop execution engine. Returns {run_id, status: "queued"} — poll with desktop_get_run. Options: name (prefix of the generated run_id), dry_run (preview the execution plan without running), no_cache (bypass the result cache), parameters overrides. | write; non-idempotent |
desktop_get_run | Get a local run’s status and result. Statuses: pending / running / completed / failed / cancelled / interrupted. | read-only |
desktop_get_run_logs | Get per-node stdout/stderr logs for a local run, with offset/limit pagination (default limit 200). | read-only |
desktop_get_queue | Get the local run queue state ({pending, running}). | read-only |
desktop_get_history | Get the local run history (finished runs). | read-only |
desktop_get_system_stats | Get host system stats from the desktop app (CPU, memory, GPU, tools). | read-only |
Resources
Resources are read-only snapshots a client can subscribe to or fetch on demand:
| URI | Description |
|---|---|
bionodulo://account | Current BioNodulo account snapshot (user + team), as JSON. |
bionodulo://credits | Current team credit balance and plan, as JSON. |
bionodulo://runs | Recent cloud workflow runs (up to 50), as JSON. |
Prompts
Prompts are pre-built instruction templates that chain several tools together:
| Prompt | What it does |
|---|---|
run_status_report(run_id) | Uses get_run_status, get_run_events and get_run_outputs for the run, then summarizes overall status, timeline, credits used, any errors, and the outputs produced. |
troubleshoot_failed_run(run_id) | Investigates a failed run: calls get_run_status for the error message, get_run_events for the failing node/step, and (for local runs) desktop_get_run_logs for stdout/stderr — then explains the root cause and suggests a concrete fix or retry strategy. |
plan_cloud_run(workflow_id) | Prepares and cost-checks a cloud run before submitting: fetches the workflow with get_workflow, checks the balance with get_credit_balance, estimates the cost for a suitable resource profile with estimate_run_cost, and confirms parameters with the user before calling submit_run. |