AI Team OS

Overview Schema Source Related Servers Discussions Admin

os_restart_api

Safely restart the AI Team OS FastAPI process after backend code changes. Guards against busy agents, port drift, and spawning before the old process exits, with optional force or dry-run checks.

Instructions

Restart the AI Team OS FastAPI process safely (standardized restart flow).

Use this after backend code changes to pick up the new version without manually killing processes. The flow has three safety guards:

Busy-agent guard — refuses to restart while any agent is working (status=busy) unless force=True.
Port-pin guard — only ever restarts on the ORIGINAL port (default 8000, read from api_port.txt). If that port is held by an unrelated process it aborts rather than drifting to a random port.
Dead-before-spawn guard — waits until the old process has fully exited and released the port before spawning the new one; never spawns on a timeout.

If the API is already down, steps 2-4 are skipped and this becomes a plain "start" of the API on its configured port.

Input Schema

TableJSON Schema

Name	Required	Description
`force`	No	Bypass the busy-agent guard and restart even while agents work.
`dry_run`	No	Only preflight imports and return the startup plan, without shutting down, spawning, or updating shared runtime files.
`source_root`	No	Explicit ai-team-os repository root to import and start. Empty preserves the current environment. Restore by explicitly passing the original repository root through this same flow.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.12.3Sep 11, 2026

addedInput schema / properties / dry_run

Added value: +{
+  "default": false,
+  "description": "Only preflight imports and return the startup plan, without\nshutting down, spawning, or updating shared runtime files.",
+  "type": "boolean"
+}

addedInput schema / properties / source_root

Added value: +{
+  "default": "",
+  "description": "Explicit ai-team-os repository root to import and start.\nEmpty preserves the current environment. Restore by explicitly\npassing the original repository root through this same flow.",
+  "type": "string"
+}

First observedv1.9.0Jul 14, 2026

TDQS

A4.7/5.0

Behavior5/5

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

No annotations are provided, so the description carries the full behavioral burden and does so exceptionally well. It discloses three concrete safety guards: the busy-agent guard, the port-pin guard, and the dead-before-spawn guard. It also explains fallback behavior when the API is already down and describes the default port source (api_port.txt).

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

Conciseness5/5

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

The description is front-loaded with the core action and then structured into three numbered safety guards. Despite being detailed, every sentence contributes operational context for a risky restart operation, and there is no redundant filler. The structure makes the safety conditions easy to scan.

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

Completeness5/5

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

For a process-restart tool with no annotations, an output schema, and full schema parameter coverage, the description is highly complete. It explains the restart flow, the safety guards, the fallback when the API is already down, and the port-pinning behavior. Return values need not be explained because an output schema exists.

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 description coverage is 100%, so the schema already documents force, dry_run, and source_root in detail. The description adds some operational context for force by tying it to the busy-agent guard, but it does not meaningfully expand on dry_run or source_root semantics beyond what the schema provides. The baseline of 3 is appropriate when the schema does the heavy parameter documentation.

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

Purpose5/5

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

The description states a specific verb and resource: 'Restart the AI Team OS FastAPI process safely.' It goes beyond a tautology by defining the standardized restart flow and clearly distinguishing this operation from generic process management. No sibling tool in the provided list covers the same process-restart purpose, so the scope is unambiguous.

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

Usage Guidelines5/5

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

The description explicitly says to use it 'after backend code changes to pick up the new version without manually killing processes.' It also states when not to use it implicitly via the busy-agent guard ('refuses to restart while any agent is working unless force=True') and describes the alternative behavior when the API is already down. This gives clear when-to-use and when-not-to-use guidance.

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

Deploy Server