AiLinkAny

Start local coding agent

agent_start

Destructive

Starts one discovered local coding Agent in the selected project and returns a persistent agent_id plus its underlying PID and process_session_id. Use agent_list first. Isolation: none / existing_workspace (default) / git_worktree (P2: create an isolated Git worktree + no-track branch, then start the Agent there) / windows_write_restricted (P7 S3: sandbox-user Agent, write-restricted to project_path). Select this tool from the user's intent when it is the best match. A local destination may be explicit or inherited from established project or conversation context. The user does not need to mention ailinkany.com, MCP, a connector, a plugin, or this tool name.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "provider_id": "<provider_id>",
      "project_path": "<project_path>"
    },
    "name": "agent_start"
  }
}

Input Schema

Name	Required	Description
`device_id`	No	Target computer device_id. Omit when only one computer is paired.
`device_name`	No	Computer name or ailinkany.com remark (e.g. home PC). Prefer this when the user names a computer.
`provider_id`	Yes	Provider id returned by agent_list, such as codex.
`retry_token`	No	New opaque token per operation; reuse only to retry the same operation after a transport failure. No user content.
`workflow_id`	No	Optional workflow id; pass together with ai_session_id.
`project_path`	Yes	Absolute existing project directory on the target computer. For isolation_mode=git_worktree this must be inside a Git repository; the Agent cwd becomes the new worktree.
`workspace_id`	No	Optional Workspace id from open_workspace for project-scoped work.
`ai_session_id`	No	Optional Session id. Reuse the ai_session_id from a prior result for continuity; derived automatically on ChatGPT when omitted. Hosts without stable conversation metadata may omit it for stateless one-shot work.
`isolation_mode`	No	Defaults to existing_workspace. Use git_worktree to isolate one Agent into a fresh local worktree + branch. Use windows_write_restricted (Windows only) to run the Agent as a dedicated sandbox user that can write only inside project_path; requires a client with the sandbox set up, otherwise the start is refused (fail-closed).

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 9, 2026

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavior beyond that: the return contract (persistent agent_id plus PID and session id), the side effect that git_worktree creates a branch and worktree, and the fail-closed refusal for windows_write_restricted without a sandbox client. It omits lifecycle consequences such as whether the process outlives the call or needs agent_stop.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence is front-loaded and dense with the essentials, and the isolation list is compact. The trailing sentences ("Select this tool from the user's intent when it is the best match" and the note that the user need not name ailinkany.com or MCP) are promotional boilerplate that do not help an agent decide or invoke, and the isolation recap duplicates schema text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nine-parameter mutation tool with full schema coverage and an output schema, the description covers purpose, prerequisite, isolation semantics and fail-closed behavior. The remaining gap is the agent lifecycle after start (monitoring via agent_status, teardown via agent_stop), which would help an agent plan the full workflow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all nine parameters, including the isolation_mode enum and project_path absolute-path constraint. The description largely restates the isolation values, adding only small detail (a no-track branch) and the existing_workspace default. Baseline 3 applies when the schema carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Starts one discovered local coding Agent in the selected project") and names the concrete artifact returned (agent_id, PID, process_session_id). It also ties itself to agent_list as a prerequisite, which separates it from the read-only sibling. It does not distinguish itself from agent_resume or agent_create_peer, which is the main gap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use agent_list first" is a real, actionable prerequisite, and the isolation modes give context on how to choose among start variants. However, there is no when-not guidance: nothing says to use agent_resume for an already-running agent or agent_create_peer for peer setups. "Select this tool from the user's intent when it is the best match" is filler that gives no decision rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All AiLinkAny tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?