Agent runtime — tool catalog

Agent runtime — tool catalog

All tools available to an agent running through the Meshi agent system. Organized into three groups:

1. Runtime-native tools — built into meshi-agent-runtime, available on every call when MESHI_RUNTIME_BACKEND=local.
2. Platform MCP tools — available via mcp_call_tool server=meshi-platform when the runtime is configured with MCP_CONFIG_JSON. Only relevant for local backend.
3. AgentBackend tools — available only when MESHI_RUNTIME_BACKEND=agent (platform-native loop). These call @meshi/core in-process and are not exposed via the platform MCP server.

See agent-runtime-integration.md for how backend mode determines which tool groups are active.

---

Runtime-native tools

Registered in agent-runtime/src/gateway/index.ts.

Files (Tigris S3)

Agent-scoped storage. Paths are prefixed per-user server-side.

Tool	Description
file_read	Read a file from the Tigris S3 bucket
file_write	Write a file to the Tigris S3 bucket
file_list	List files matching a prefix
file_delete	Delete a file

Web

Tool	Description
web_fetch	Fetch a webpage or make an HTTP request; returns rendered content
web_search	Keyword/semantic web search; driver selected by WEB_SEARCH_DEFAULT env (duckduckgo, jina, exa, google, bing)
web_parse	Parse structured content from a fetched HTML page (links, text, metadata)

Code execution (Vercel Sandbox)

Code runs in ephemeral Firecracker microVMs — no host filesystem access. Sandboxes are per-call and torn down in finally. See agent-runtime/docs/security-audit.md for sandbox isolation notes.

Tool	Description
code_execute	Execute a JavaScript or TypeScript snippet; default 30 s timeout (max 300 s)
code_run_script	Run a multi-line JS/TS script with stdin/stdout capture

Vector memory (Neon pgvector)

Tool	Description
vector_store	Store content with an embedding for later retrieval
memory_recall	Hybrid search (vector + keyword) against stored memories; returns ranked results
rag_query	Retrieve relevant context and format it as a prompt-ready string

Advanced RAG features (chunking strategies, multi-query, LLM reranking) are available via POST /api/rag/* on the runtime — see agent-runtime/src/api/advanced.ts.

Cron / scheduled tasks

Tasks are stored in the runtime’s Postgres schema and executed by the runtime’s cron subsystem.

Tool	Description
cron_schedule	Schedule a recurring or one-shot task. Accepts cron expression, @every 5m, or ISO timestamp
cron_list	List all scheduled tasks with their status
cron_update	Update schedule or goal of an existing task
cron_pause	Pause a task (stops firing until resumed)
cron_resume	Resume a paused task
cron_remove	Delete a task permanently

MCP federation

Lets the agent call tools on any MCP server, including the Meshi platform server.

Tool	Description
mcp_call_tool	Call a tool on a configured MCP server: { server, method, params }
mcp_add_server	Register an additional MCP server at runtime (stdio or http)
mcp_remove_server	Remove a registered server and tear down its connection

The meshi-platform server is pre-configured via MCP_CONFIG_JSON. Do not add a static x-meshi-runtime-user-id header to the config — the runtime injects a fresh per-user JWT on every call.

Skills

Skills are git-cloned tool bundles that extend the agent’s capabilities at runtime.

Tool	Description
skill_install	Clone and install a skill from a git URL or local path
skill_execute	Run a registered skill
skill_list	List installed skills
skill_remove	Remove a skill by name
skill_search	Search installed skills by name substring or tag
skill_audit	Audit a skill’s content against the high-risk pattern set (before execution)

Skills are installed as a shared resource (not per-user). Restrict skill_install to admin users in production — see agent-runtime/docs/security-audit.md MED-4.

Hooks

Hooks intercept events in the agent loop (pre/post tool execution, on message, etc.).

Tool	Description
hook_register	Register a hook on a named event with a priority
hook_list	List registered hooks
hook_unregister	Remove a hook by name
hook_test	Fire a synthetic event against a hook for testing

Composio (SaaS integrations)

Delegates to the Composio SDK for OAuth-managed SaaS tool execution. Covers Google Workspace, Microsoft 365, Slack, Linear, GitHub, and 200+ other apps.

Tool	Description
composio	Multiplex entry point: operation ∈ {list, list_accounts, execute, connect}. Pass app, action_name, params, and entity_id.

entity_id maps to the authenticated user’s Composio identity — passed via the x-entity-id header from the platform or set explicitly by the caller.

---

Platform MCP tools

Available inside the agent loop via:

{ "tool": "mcp_call_tool", "server": "meshi-platform", "method": "tools/call",
  "params": { "name": "<tool>", "arguments": { ... } } }

Registered in packages/mcp/src/server.ts. Each call is automatically scoped to the authenticated user (verified via x-meshi-runtime-user-id JWT — see agent-runtime-integration.md).

Profile

Tool	Description
get_profile	Current user’s display name, role, company, confirmed traits, latest brief
get_brief	Current user’s canonical brief (LLM-synthesized professional summary)
update_profile	Update display name, current role, and/or current company

Contacts and connections

Tool	Description
import_contacts	Import one or more contacts (name + email/linkedinUrl + arbitrary extra fields). Accepts a source label.
add_person	Add a single person to the user’s network (name + email or linkedinUrl required). Auto-enriches in the background.
remove_person	Soft-delete a person from the user’s network (severs contact/connection edges; entity record preserved).
list_contacts	List all contacts imported by the current user
list_connections	List the current user’s LinkedIn connections with profile data and match tier

Search

Tool	Description
search_people	Semantic search across the user’s network using natural language. type ∈ {brief, traits}

Goals

Tool	Description
list_goals	List active goals (proposed + confirmed)
create_goal	Create a new goal (enters proposed state)
confirm_goal	Confirm a proposed goal (makes it active for matchmaking)

Matchmaking

Tool	Description
run_match	Find matches for a specific goal (goalId) or across all confirmed goals if goalId is omitted. Returns scored candidates with profiles.
get_readiness	Per-goal readiness stages (review → extraction → embedding → match), profile-level blockers, and a nextStep instruction to unblock matching. Use before run_match to diagnose why matching might fail.
discover	Combined overview: readiness status, goal landscape, and top matches across all confirmed goals in one call. Use as the starting point for a discovery conversation.

Contact detail

Tool	Description
get_contact_profile	Full profile for a network contact: canonical brief, traits by dimension, career timeline
get_contact_evidence	Raw source evidence chunks for a contact’s traits (pass sourceRecordIds from trait evidence_refs)

Traits

Tool	Description
list_traits	Current user’s traits, optionally filtered by dimension (skill, values, experience, circles, personality, location)
assert_trait	Assert a new confirmed trait for the current user
review_trait	Confirm, reject, or edit a proposed trait claim

---

AgentBackend tools (MESHI_RUNTIME_BACKEND=agent only)

These tools are only available when the platform is running its native agentic loop (AgentBackend, activated by MESHI_RUNTIME_BACKEND=agent). They call @meshi/core service functions in-process and are not registered on the platform MCP server. Under local backend (the default deployment), none of these tools exist — the external runtime cannot reach them.

Source: packages/api/src/agent-backend.ts, AGENT_TOOLS array.

The AgentBackend loop runs up to 8 tool rounds, retries LLM calls up to 2 times on 5xx/network errors, and has a 120 s overall timeout.

Onboarding

Tool	Arguments	Description
get_onboarding_status	(none)	Return the current user’s onboarding state (status, phase, step, LinkedIn URL, goal count, and readiness). Call this first to understand what the user has set up.
start_onboarding	linkedinUrl: string	Create the user’s entity and kick off LinkedIn enrichment. Sets state to processing/enrichment.
update_linkedin_url	linkedinUrl: string	Replace the LinkedIn URL and requeue enrichment. Accepts any non-completed state including action_required.
complete_onboarding	(none)	Mark onboarding as complete. Fires ONBOARDING_COMPLETED. Requires status=review + phase=goals_review and at least one confirmed goal — the same readiness gate as the HTTP route without force=true. The agent tool never passes force; use the HTTP POST /api/v0/onboarding/complete { force: true } for the conversational path where the readiness gate should be skipped.

Profile

Tool	Arguments	Description
get_profile	(none)	Display name, role, company, confirmed traits, latest brief.
get_brief	(none)	The user’s current canonical brief (LLM-synthesized professional summary).
update_profile	displayName?, currentRole?, currentCompany?	Update name, role, and/or company.

Contacts and connections

Tool	Arguments	Description
import_contacts	contacts: [{name, email?, linkedinUrl?, role?, company?}], source?	Bulk-import contacts.
list_contacts	(none)	All contacts imported by the current user.
list_connections	(none)	LinkedIn connections with profile data and match tier.
get_connections_progress	(none)	Enrichment pipeline progress: enriched / traits-inferred / goals-inferred / briefs-complete / match-ready counts.

Search

Tool	Arguments	Description
search_people	query: string, limit?: number, type?: 'brief'|'traits'	Semantic search across the user’s network. Requires embedding provider configured (embed fn injected from composition root).

Goals

Tool	Arguments	Description
list_goals	(none)	Active goals (proposed + confirmed).
list_match_goals	(none)	Confirmed goals available for matchmaking.
create_goal	value: string	Create a new goal in proposed state.
confirm_goal	goalId: string	Confirm a proposed goal (activates it for matchmaking).

Matchmaking

Tool	Arguments	Description
run_match	goalId: string (required), limit?: number	Find matches for a specific confirmed goal. Note: the Platform MCP run_match makes goalId optional (matches across all confirmed goals if omitted) — the AgentBackend tool requires it explicitly.

Traits

Tool	Arguments	Description
list_traits	dimension?: string	All traits, optionally filtered by dimension.
assert_trait	dimensionKey: enum, value: string	Assert a new confirmed trait. Valid dimensions: skill, experience, values, circles, personality, location.
review_trait	claimId: string, action: 'confirm'|'reject'|'edit', newValue?: string	Confirm, reject, or edit a proposed trait claim.

Tool result size limit

AgentBackend truncates any single tool result to 12 000 bytes to prevent context blowup. Results exceeding that limit are sliced with a ...[truncated] suffix.