Tools Reference

colabhive-mcp exposes two families of tools, with two naming conventions that live side by side:

1. Manifest / action tools — the hive's models and endpoints as invocable tools. Their slug is the endpoint name (endpoint_name in the DB), kebab-case, e.g. qwen-2.5-7b-instruct-public, embeddings-public, web-fetch-public. This list is 100% DB-driven — it is whatever your account can see, fetched live from GET /api/builder/v1/mcp/manifest. Plus two static platform operations (training.merge, training.retrain_on).
2. Built-in control-plane tools — 15 operational tools (snake_case) for datasets, training, and model management. These are baked into the server, not derived from the manifest.

server.list_tools() returns the filtered manifest tools plus the 15 built-ins.

Because the manifest is per-account and dynamic, this page does not hardcode a catalog of model slugs. For the authoritative live list, call GET /api/builder/v1/mcp/manifest, GET /api/builder/v1/actions?visibility=public, or browse the Model Catalog. The example slugs below are illustrative.

---

Platform operations (kind=operation)

Two static tools, injected into every authenticated account's manifest (before the model tools) so agents can build new capabilities: merge trained models/adapters and retrain on top of any model. Both create jobs that count against your training quota, so they carry costHint: "training_quota" and sideEffects: ["creates_job", "creates_model_version", "consumes_training_quota"].

Slug	Purpose	Backing endpoint	latencyClass
training.merge	Merge N trained models/adapters into a base → a new servable model_version (weight arithmetic, CPU).	POST /training/merges	minutes
training.retrain_on	Fine-tune on top of an existing trained/merged model_version (or HF/job/storage) as the base.	POST /training/runs	long

Inputs reference models by ArtifactRef (hf | model_version | job | storage).

training.merge input (summary):

{
  "name": "qwen-domain-base",
  "base": { "type": "hf", "repo_id": "Qwen/Qwen2.5-7B-Instruct" },
  "method": "adapter_merge",
  "adapters": [ { "type": "model_version", "version_id": "..." } ],
  "sources": [],
  "weights": [],
  "precision": "bf16",
  "hardware_preference": "cpu_only"
}

method ∈ adapter_merge (default) | slerp | ties | dare. Only name is required.

training.retrain_on input (summary):

{
  "job_name": "domain-expert-v2",
  "model_config_id": "...",
  "dataset_id": "...",
  "base": { "type": "model_version", "version_id": "..." },
  "parent_job_id": null,
  "hyperparameters": { "learning_rate": 0.0002, "epochs": 3 }
}

Required: job_name, model_config_id, dataset_id, base.

These deliver the generic model flywheel — merge capabilities, retrain-on-top, repeat. See the flywheel concept and the merge & retrain how-to.

---

Built-in control-plane tools

These 15 tools (snake_case) wrap the Builder API's operational surface — datasets, training runs, and model/endpoint management. They are always present, independent of the manifest. Agents such as SuperClaw / OpenCode use exactly these names.

Discovery & inference

Tool	Purpose	Required args
list_endpoints	List invocable inference endpoints (base models + your deployed models) with readiness.	— (optional: include_readiness, task_type, search, limit)
get_endpoint	Get an endpoint's details and readiness (warm/cached/cold).	endpoint_id
run_inference	Run sync inference on an endpoint. input is the model's input object (for LLMs: {messages, tools?, tool_choice?, max_tokens?}; for specialists, the endpoint's schema). Returns the model output (OpenAI-shaped for LLMs, including tool_calls).	endpoint_id, input
list_models	List your trained/registered models.	—

Training lifecycle

Tool	Purpose	Required args
list_trainable_models	List base model configs available to fine-tune/train (id, name, category, framework).	—
get_model_schema	Get the hyperparameter schema for a trainable model config.	model_config_id
list_datasets	List datasets registered for your account.	—
create_dataset	Register a new dataset (metadata).	name
create_training_run	Start a real training run. operating_mode ∈ economy | balanced | performance. Returns the run id.	job_name, model_config_id, dataset_id
list_training_runs	List your training runs with status.	— (optional: limit)
get_training_run	Get a run's status/details.	run_id
get_training_metrics	Get metrics (loss curves, eval scores, feature importance when produced).	run_id
get_training_logs	Get logs for a run.	run_id
cancel_training_run	Cancel a running training run.	run_id
register_for_inference	Deploy a finished run as an inference endpoint (it becomes an invocable model tool).	run_id

---

Model & endpoint tools (manifest-driven)

Every model/endpoint your account can see becomes a tool whose slug is its endpoint_name. The kind is computed server-side (never hardcoded) from the endpoint's category/task:

kind	What it is	Example slugs (illustrative — check the live catalog)
llm	Instruction-tuned language models (vLLM / transformers)	qwen-2.5-7b-instruct-public, mistral-7b-instruct-public, phi-3.5-mini-public, deepseek-distilled-7b-public, hf-google-gemma-2-9b-it
specialist	Single-purpose ML endpoints	embeddings-public, rerank-public, translate-public, stt-public, moderate-public, ocr-public
tool	Network-enabled utilities (sideEffects: ["network"])	web-fetch-public, web-search-public, web-scrape-public, geo-geocode-public
generative	Image / audio / video / speech generation	z-image-turbo, hf-black-forest-labs-FLUX.1-dev, wan22-video, kokoro-tts, hf-facebook-musicgen-small
model	Trainable/forecasting models (tabular, time series)	patchtst-forecasting, prophet-forecasting, xgboost-regression, random-forest-regression
trained_model	Your trained/merged models (per-account)	appears only in your manifest, after you train/register

Each tool's full manifest (input/output schemas, examples, side-effects, cost/latency hints) is fetched at runtime via GET /api/builder/v1/mcp/manifest/{slug}. To invoke one: run_inference (built-in), or the agent calls the tool by its slug directly.

Common input shapes

• LLMs: {"messages": [{"role": "user", "content": "..."}], "temperature": 0.7, "max_tokens": 512}
• Embeddings: {"text": "..."} → {"embedding": [...]}
• Rerank: {"query": "...", "documents": [...]} → {"scores": [...]}
• Tools (web-fetch etc.): {"url": "..."} — see the tool's manifest for the exact schema.

Context windows, dimensions, prices, and readiness are per-endpoint and change over time — read them from the tool's manifest or the Model Catalog, not from this page.

Trained models (kind=trained_model)

These are per-account: each appears in your manifest only after you train it via the Training API and it is registered as an endpoint. Its manifest carries a lineage block pointing back to its base and dataset. Once published (visibility=public) and reviewed, a trained model can also appear in other accounts' manifests.

---

Filtering the tools your agent sees

Use config flags — useful for cost control and reducing context bloat:

# Only LLMs and your own trained models
export COLABHIVE_ALLOW_KINDS="llm,trained_model"

# Only management + specialists (exclude LLMs, generative, tools)
export COLABHIVE_ALLOW_KINDS="specialist,trained_model"

# Only stable tools (exclude experimental/beta)
export COLABHIVE_STABILITY=stable

# Allowlist by slug glob
export COLABHIVE_ALLOW_TOOLS="qwen-*,embeddings-public,web-fetch-public"

Filters apply to the manifest tools; the built-in control-plane tools are always available.

---

See also

• Manifests — full schema for tool metadata
• Model Catalog — per-model documentation
• Actions API list endpoint — programmatic discovery