Skip to docs content
Browse documentation
On this page

Search and execute

Minion's MCP surface is two tools. search finds capabilities, guides, packages, notes, team skills and connected MCP server tools. execute runs an ephemeral module that calls what you found. Covers how they work together and the inputs an agent actually passes.

Your agent connects to Minion over MCP and starts with two tools. That is the whole public surface: search finds the right thing, then execute runs it. Capabilities, saved packages, notes, team skills, connected MCP servers and official guides stay behind those two doors instead of appearing as a tool list.

This page is the playbook for those two calls. The same tools drive the loop in How Minion works .

Search

search finds built-in capabilities, official guides, saved packages, notes, published team skills and the tools of connected MCP servers. Secret names are indexed for discovery, but their values never are.

What search enables

An agent can describe a goal in natural language and get a ranked shortlist — type, title, one-line summary, and an entity ref — instead of loading hundreds of tools. Capability hits include a call signature and an example, so the next step is often a single execute.

How an agent calls it

Three useful shapes:

  • Natural language — { "query": "send a message" } ranks matches for that task.
  • Domain browse — an empty call {} returns a domain index: each row has the domain id, a one-line description, a capability count, a few sample names and the guides for that domain. Follow up with { "domain": "email" } to list that domain, or { "query": "…", "domain": "email" } to rank only there. Remote MCP servers you have connected show up as hits of kind mcp-server and mcp-tool.
  • Entity lookup — { "entities": ["{kind}:{id}"] } opens hits in full. The kind is capability, guide, package, note, skill, mcp-server or mcp-tool. Pass 1–10 refs to load related details in one call. Guide refs accept #{heading} to open one section, or #L10-L20 for lines.

Capability detail includes the call signature and a ready-to-run execute snippet. Guide detail is the official markdown. Search also returns a conversationId: pass it back on follow-up searches.

See Search for every field.

Execute

execute runs one ephemeral ES module inside Minion's sandbox. The module must export default async function main(params).

What execute enables

One tool surface reaches the whole platform: call a discovered capability, import a saved package export, fetch with a secret placeholder, compose several steps, and return a structured result. The agent adapts a short module instead of learning a new MCP tool per capability.

How an agent calls it

Pass code: a single module string. Call built-in capabilities as minion.<domain>.<fn>(params), either through the global minion or by importing it from minion:runtime. Remote MCP server tools are minion.mcp["name"].tool_name(params). Known package exports use a static minion:@scope/package/export import.

Optional params is a JSON object passed as the first argument to that default export. Name the argument params. Capability search detail already emits the module; adapt it, then execute. Optional idempotencyKey makes a repeat call with the same key return the stored run instead of running again.

import { minion } from 'minion:runtime'

export default async function main(params) {
	return await minion.email.send(params)
}

minion.email.send mails verified destinations, or your own account email when to is omitted (subject plus text or html). See Execute and workflows for minion:runtime helpers, workflows, and timeouts.

The result is one JSON text block: runId, then result (or error), logs and replayed. It may also carry the one or two most relevant memories.

Search first, then execute

  1. Search for the outcome — a query, a domain list, or a known entity ref.
  2. Read the ranked hit or entity detail. Capability detail includes the execute snippet and the input type.
  3. Execute with that adapted snippet. Put varying capability args in params so the same code stays the same.
  4. Reuse the conversation id from the search response on the next search in the same conversation.
  5. Save the working module as a package when the behavior should live past this chat — Package lifecycle .

Official guides open with search({ entities: ["guide:{id}"] }).

Example agent inputs

Copy-pasteable argument objects. Field names match the MCP tool schemas.

search

Empty call — domain index:

{}

Natural language:

{ "query": "send a message" }

Rank inside one domain:

{ "query": "send a message", "domain": "email" }

List one domain in registry order:

{ "domain": "jobs" }

Open one official guide:

{ "entities": ["guide:package_with_daily_job"] }

Open several related entries:

{
	"entities": ["guide:package_with_daily_job", "guide:edit_a_saved_package"]
}

Open a capability (returns the execute snippet):

{ "entities": ["capability:email.send"] }

Open a connected MCP server, a saved package, or a team skill:

{ "entities": ["mcp-server:linear"] }
{ "entities": ["package:my-package"] }
{ "entities": ["skill:deploy-app"] }

Open one guide heading:

{ "entities": ["guide:receive_a_webhook#receive-a-webhook-with-a-package"] }

execute

Module plus optional params — params is the first argument on the default export:

{
	"code": "import { minion } from 'minion:runtime'\n\nexport default async function main(params) {\n\treturn await minion.email.send(params)\n}",
	"params": {
		"subject": "Hello from Minion",
		"text": "Notify-self mail from an execute module."
	}
}

The same module, written as source (this is the code string):

import { minion } from 'minion:runtime'

export default async function main(params) {
	return await minion.email.send(params)
}

Call a saved package export whose name is known when you write the module:

import whatShipped from 'minion:@your-org/favorite-bot-ships/whatShipped'

export default async function main() {
	return await whatShipped()
}
{
	"code": "import whatShipped from 'minion:@your-org/favorite-bot-ships/whatShipped'\n\nexport default async function main() {\n\treturn await whatShipped()\n}"
}

Package imports only resolve inside your own team (@<org slug>/...).

Where to go next