Reference
All 80 tools
Four levels: guide, workflow, molecule, atom. Tools marked "changes state" ask before acting. Set NOVAOS_MCP_PROFILE=beginner to hide atoms.
| Tool | Domain | Level | What it does |
|---|---|---|---|
novaos_template | agent | guide | Lists or shows proven code templates: agent-python (server.py dispatcher, novaos_helpers.py with LLM gateway/progress/heartbeat/RAG/MCP/returned writes, manifest, Dockerfile, tests), backend-python / backend-typescript (service-account client with stream resume and capacity handling), mcp-python (read-named MCP server), eval (suite). |
novaos_agent_create | agent | molecule changes state | Creates a ready-to-publish Python A2A agent from a battle-tested template: one dispatcher skill (ping/chat/models/search), LLM gateway calls with disable_fallbacks + served-model check + cost, heartbeat progress, RAG search, returned-writes helper, read-only-FS Dockerfile, contract tests, and an AGENTS.md for AI assistants. |
novaos_agent_lint | agent | molecule | Static check of an agent project against every known NovaOS publish/run trap: manifest schema, base_image label, publisher placeholder, version drift with code, multi-skill routing, memory prefetch, card drift (manifest vs @agent.skill), lowercase SkillResult statuses, ctx.tools.llm, wrong import name, LLM calls without disable_fallbacks, MCPClient misuse, RAG query, old vendored SDK, TestPyPI, Dockerfile root/port, .dockerignore hiding prompts, tracked .env. |
novaos_agent_card | agent | atom | Runs the SDK's agent-card capture (what publish does) to prove the module loads and the declared skills match. |
novaos_cli_init | agent | atom changes state | Runs `novaos-cli init` exactly (raw scaffold). |
novaos_manifest_validate | agent | atom | Runs `novaos-cli manifest validate --json` (offline, the same validator publish uses) for an agent manifest, or `mcp validate` for an MCP server manifest. |
novaos_auth_login | auth | molecule changes state | Signs in to NovaOS through novaos-cli: opens the browser sign-in page (OAuth + PKCE), waits for it to finish (up to ~2 minutes), then reports the identity, org and roles. |
novaos_env_setup | auth | molecule changes state | Registers an environment with novaos-cli (env add) from a known preset (staging = US staging, fde = FDE US, staging-eu) or from URLs you give, optionally makes it active for both the CLI and this server. |
novaos_auth_status | auth | atom | Checks sign-in for an environment without changing anything: subject, organization, roles, token lifetime and missing recommended scopes. |
novaos_env_list | auth | atom | Lists NovaOS environments known to novaos-cli (~/.novaos/environments.json) and this server's presets, marks the active one, and flags the CLI trap where an unknown env name silently falls back to 'local'. |
novaos_env_show | auth | atom | Shows every resolved service URL (gateway, agent-ops, mcp-ops, review, IAM, marketplace, S2S/RAG, LLM gateway) for an environment. |
novaos_env_use | auth | atom changes state | Makes an environment active for this server and for novaos-cli. |
novaos_org_list | auth | atom | Lists the organizations the signed-in user belongs to (novaos-cli auth org list). |
novaos_org_use | auth | atom changes state | Makes an organization active for the CLI and this server (org-scoped token). |
novaos_publisher_show | auth | atom | Shows the marketplace publisher slug used in manifest 'publisher' (novaos-cli publisher show). |
novaos_conversation_get | chat | atom | Reads one platform conversation and its messages (GET /api/v1/conversations/{id} and /messages). |
novaos_conversation_history | chat | atom | Shows the locally kept history (and gateway thread id) of a conversation created by novaos_ask_agent {conversation}. |
novaos_conversation_update | chat | atom changes state | Updates a platform conversation (PATCH /api/v1/conversations/{id}): title, context_summary, token_budget, context_strategy. |
novaos_conversations | chat | atom | Lists platform conversations (GET gateway /api/v1/conversations, filter by instance_id and status active|archived|deleted). |
novaos_hitl_decide | chat | atom changes state | Sends a native human-in-the-loop decision for a run waiting on approval (WAITING_USER / WAITING_AUTH): POST /api/v1/conversations/{thread_id}/hitl {approved}. |
novaos_error_catalog | debug | guide | Lists the catalog of known NovaOS errors, codes and known platform bugs this server recognizes, with fixes. |
novaos_explain_error | debug | guide | Explains any NovaOS error text (from the CLI, SDK traceback, HTTP response, run event, UI message or JSON-RPC code): who is at fault (NovaOS platform, CLI, your input, your setup, auth, capacity), the likely cause, the fix, and whether it is a known NovaOS bug. |
novaos_job_status | debug | guide | Shows the state and last log lines of a background job (installs, builds, publish, ingest). |
novaos_report_bug | debug | guide | Drafts a ready-to-file bug report for the NovaOS team from an error (title, environment, versions, exact request, request/run ids, expected vs actual, repro steps, workaround). |
novaos_run_diagnose | debug | molecule | Explains why a run failed or hung: reads the run, its events, the platform trace (novaos-cli debug trace) and, if agent_id is given, the agent logs for that run; classifies the failure (agent code vs platform capacity vs auth/scope vs MCP refusal vs stream cut) and says what to do. |
novaos_agent_logs | debug | atom | Fetches a deployed agent's logs (novaos-cli agent logs). |
novaos_kb_collection_create | knowledge | molecule changes state | Creates a RAG collection with the right embedding model for the environment's region (US text-embedding-3-small/1536, EU text-embedding-004/768; a wrong model fails only later at ingest), idempotently (client_request_id), and saves its id under a local name. |
novaos_kb_graph | knowledge | molecule changes state | GraphRAG on a collection: action=build starts building the knowledge graph (a write; takes minutes), status shows progress, local asks a relationship question about specific entities (graph_query), global asks a corpus-wide summary question (global_query). |
novaos_kb_ingest | knowledge | molecule changes state | Ingests local files into a collection the robust way: checks size (7 MiB practical cap), skips files already ingested (sha256), picks a parser from live capabilities (docling / pymupdf / OCR / xlsx / anydoc), parses once with a persisted artifact, ingests from the parse with sensible chunking, polls jobs, fixes the duplicate-upload bug, and records document ids. |
novaos_kb_search | knowledge | molecule | Hybrid (vector + keyword) search over a collection with the NovaOS planner OFF (faster, predictable), deduped hits, optional document filter. |
novaos_kb_capabilities | knowledge | atom | Lists the RAG parsers (sync and async: text, csv, html, pymupdf, pdfplumber, docx, xlsx, docling, surya OCR, anydoc ...) and chunking strategies this environment offers (GET s2s /rag/capabilities). |
novaos_kb_collection_delete | knowledge | atom destructive | Permanently deletes a RAG collection and its documents. |
novaos_kb_collections | knowledge | atom | Lists RAG collections visible in the org (they are org-wide and shared across apps) plus the names/ids saved on this machine. |
novaos_kb_documents | knowledge | atom | Lists documents in a collection with chunk counts and content hashes. |
novaos_kb_parse | knowledge | atom | Parses one local file with a chosen parser and returns text/tables/page count, without adding it to a collection. |
novaos_kb_tool | knowledge | atom changes state | Calls one NovaOS RAG tool over S2S JSON-RPC with exact arguments. |
novaos_llm_models | llm | atom | Lists the model directory of the NovaOS LLM gateway (GET gateway /api/v1/llm/models; developer or platform-admin role). |
novaos_instance_install | marketplace | molecule changes state | Installs an agent for the caller (POST marketplace /api/instances, adapter_type A2A, CSRF header) and waits until READY. |
novaos_catalog_search | marketplace | atom | Lists agents in the marketplace catalog (GET marketplace /api/agents), optionally filtered by text. |
novaos_instance_list | marketplace | atom | Lists installed agent instances visible to the caller (GET gateway /api/v1/instances): instance_id, agent, version, status. |
novaos_mcp_publish | mcp | molecule changes state | Publishes an MCP tool server (novaos-cli mcp publish): validates, checks names, reads secrets from the git-ignored .env next to the manifest, builds and pushes, submits for review. |
novaos_mcp_server_create | mcp | molecule changes state | Creates a Python MCP tool server (FastMCP, streamable HTTP :3000) that agents call as <publisher>.<name>.<tool>: read-named example tools, tenant taken from trusted gateway headers, non-root Dockerfile with a working health check (the CLI template's curl check fails on python:slim), and a test that enforces NovaOS's read/write naming rules. |
novaos_mcp_name_check | mcp | atom | Classifies MCP tool names exactly like NovaOS does (by leaf name, fail-closed). |
novaos_cost_estimate | metering | guide | Estimates the cost of model calls from token counts with list prices (USD per 1M tokens). |
novaos_usage | metering | atom | Reads NovaOS platform cost for your org (marketplace admin cost API): summary (total, by category, top agents and plugins/models), breakdown (group_by agent/operation_type/plugin), records, per-agent usage, a service account's usage, or one operation, over a period (7d, 30d, YYYY-MM, all). |
novaos_agent_publish | publish | molecule changes state | Publishes an agent version: pre-flight (Docker running, signed in, lint errors, placeholder publisher), then `novaos-cli publish` (build, card capture, push, submit for review) as a background job. |
novaos_wait_for_approval | publish | molecule | Polls a review until it is ACTIVE or REJECTED (up to ~45 s per call). |
novaos_agent_list | publish | atom | Lists the publisher's agents with agent ids (marketplace developer API via novaos-cli agent list). |
novaos_agent_versions | publish | atom | Lists published versions of an agent (novaos-cli release list --agent <agent-id>). |
novaos_publish_history | publish | atom | Lists agents and MCP servers published through this server (env, version, review id, agent id). |
novaos_publish_status | publish | atom | Shows the review pipeline status of a publish (PENDING_SCAN, SCANNING, PENDING_REVIEW, APPROVED, ACTIVE, REJECTED, ROLLED_BACK). |
novaos_api | raw | atom changes state | Raw authenticated HTTP call to a NovaOS service (gateway, agentOps, mcpOps, review, marketplace, s2s, llm, connectorHost, metering, iam) with errors translated. |
novaos_cli | raw | atom changes state | Runs a novaos-cli command with --env set explicitly and returns its output (JSON when --json). |
novaos_ask_agent | runs | molecule changes state | One call to talk to a deployed agent: finds your instance (by instance_id, or by agent name among your instances), starts a run and waits up to ~45 s for the answer (call novaos_run_wait if still running). |
novaos_run_wait | runs | molecule | Follows a run until it finishes (stream with Last-Event-ID resume, then polling) within ~45 s per call, and returns the answer, progress, error and cost. |
novaos_run_events | runs | atom | Reads the stored events of a run (GET /api/v1/runs/{id}/events?after=) and summarizes them: answer, progress labels, error, usage, cold/warm start. |
novaos_run_get | runs | atom | Reads one run (GET gateway /api/v1/runs/{id}): status, timestamps, error. |
novaos_run_start | runs | atom changes state | Starts one run on an instance (POST gateway /api/v1/execute) and returns run_id + thread_id immediately. |
novaos_sa_setup_guide | service-account | guide | Step-by-step (with browser steps) to create a NovaOS service account for a backend app: create the SA and its credential in the Organization Console, grant scopes/roles and tool grants, store the secret locally, install the agent FOR the SA (its own instance id), test a run, and wire your backend. |
novaos_app_integration_code | service-account | molecule changes state | Writes a production-grade NovaOS client module into your backend: service-account token mint + cache (resource + organization_id), execute with idempotency, SSE stream with Last-Event-ID resume, poll-and-replay recovery after cuts (never re-run), 429 capacity backoff, pod-quota detection, gateway thread mapping with THREAD_NOT_FOUND retry, and friendly errors. |
novaos_sa_credentials_file | service-account | molecule changes state | Creates a private credentials file (~/.novaos-mcp/secrets/<ref>.json, mode 600) with blanks for client_id, client_secret and org_id, and opens it in a text editor so the USER pastes the secret there. |
novaos_sa_token_test | service-account | molecule | Mints a client_credentials token for a stored service account (resource urn:novaos + organization_id, without which NovaOS silently 403s), and reports org, granted scopes and what is missing for running agents, MCP tools, models, installs and RAG. |
novaos_sa_list | service-account | atom | Lists service-account credential refs stored on this machine (names only, never secrets) and which is the default. |
novaos_install_plan | setup | guide | Returns the exact install steps for this operating system for one or more components (brew, python, node, git, docker, wsl, novaos-cli). |
novaos_doctor | setup | molecule | Checks everything NovaOS development needs on this computer (Python 3.12+, Node, Git, Docker running, novaos-cli version, the SDK in a project venv) and says what is missing, why it matters, and how to fix it. |
novaos_install | setup | molecule changes state | Installs one component (python, node, git, docker, novaos-cli, or upgrades novaos-cli) using the OS package manager, as a background job. |
novaos_python_env | setup | molecule changes state | Creates (or repairs) a Python virtual environment in <project_dir>/.venv with Python 3.12+ and installs the pinned public SDK (novaos-agent-sdk) from public PyPI, plus optional local-server deps (fastapi, uvicorn, pydantic). |
novaos_sdk_versions | setup | atom | Lists published versions of the Python SDK (PyPI) and novaos-cli (npm) and the recommended ones, so you can pin or upgrade deliberately. |
novaos_docs | start | guide | Searches the bundled NovaOS field guides (official docs plus lessons learned building AssetNova and other apps): setup, agents, manifest, CLI, knowledge/RAG, publish and approvals, instances, service accounts, runs and streaming, chat, LLM gateway, metering, errors. |
novaos_start_here | start | guide | Orientation for anyone (including non-technical users): checks this computer, the NovaOS environment and sign-in, the current project and saved progress, then recommends the single best next step and the guided journey to follow. |
novaos_tool_index | start | guide | Lists every tool in this server grouped by domain and tier (guide, workflow, molecule, atom). |
novaos_ui_guide | start | guide | Returns the URL and exact clicks for NovaOS web UI tasks (for the AI client's browser tool or the user): approvals, publishes, publisher_profile, install_agent, install_for_service_account, service_accounts, rotate_secret, mcp_servers, external_connector, agent_logs, spending, rate_limits, models_connectors. |
novaos_workflow_continue | start | workflow changes state | Continues a journey. |
novaos_workflow_list | start | workflow | Lists the guided, resumable NovaOS journeys (zero_to_hero, build_agent, ship_agent, knowledge_base, service_account_app, ...) with what each achieves and its steps. |
novaos_workflow_retry | start | workflow changes state | Resets the failed or stuck current step of a journey and runs it again. |
novaos_workflow_start | start | workflow changes state | Starts a resumable journey and immediately runs its first steps. |
novaos_workflow_status | start | workflow | Shows the step checklist and saved context of a journey run; without run_id lists recent runs. |
novaos_test_deployed | testing | molecule changes state | Tests the PUBLISHED and INSTALLED agent through NovaOS: each case starts a real run (execute + stream) and checks status and answer (contains, exact_match, regex). |
novaos_agent_test | testing | atom | Runs the agent's contract tests (pytest in .venv): version sync, one skill, operations enum, statuses, input parsing. |
novaos_eval_platform | testing | atom changes state | Lists platform eval runs for an agent (novaos-cli eval list) or starts a platform suite run (eval run; may be unavailable on some envs). |