Tools

The server exposes a focused set of tools. Read tools are available on any connection; write tools appear only on a read-and-write connection. Lists are paginated (pass the nextCursor from a previous response to get the next page).

Tools are namespaced by product surface: *_platform_* tools work with the agents you build yourself, and *_workforce_* tools work with your Octavus Agents. They are different things and never overlap.

Platform agents

The agents you build with the SDK/CLI, inside a project - distinct from your Octavus Agents below. get_platform_agent and archive_platform_agent take the agent's agentId from list_platform_agents; deploy_platform_agent addresses the agent by the slug in its settings (like octavus sync).

Tool	Access	Description
`list_projects`	read	List the projects you can access.
`list_platform_agents`	read	List the platform agents in a project.
`get_platform_agent`	read	Get an agent as CLI-format files: `settings`, `protocol.yaml`, `prompts`, `references`.
`validate_platform_agent`	read	Validate an agent definition without saving (dry run), like `octavus validate`.
`deploy_platform_agent`	write	Create or update an agent from CLI-format files, like `octavus sync`. Supports partial (changed-only) updates.
`archive_platform_agent`	write	Archive an agent (soft delete): it stops appearing in the project and its slug is freed; history is preserved.

Editing an agent

A typical write loop mirrors the CLI:

get_platform_agent to fetch the current files.
Edit locally.
validate_platform_agent to check the change.
deploy_platform_agent to apply it. By default only the files you send change and the rest are preserved; set replace: true to replace the full prompt/reference set.

Sessions

Sessions belong to platform agents.

Tool	Access	Description
`list_sessions`	read	List recent sessions in a project, optionally filtered to one platform agent.
`get_session_trace`	read	Get a session's execution trace as readable markdown for debugging.

Traces are available while the session log is warm (about 24 hours after the run). Noisy model-request telemetry is excluded by default; pass includeModelRequests: true to include it.

Octavus Agents

Your Octavus Agents (the "workforce") - distinct from the platform agents above. Identify one by its agentId from list_workforce_agents.

Tool	Access	Description
`list_workforce_agents`	read	List the Octavus Agents you can access.
`list_workforce_threads`	read	List an agent's chat threads (needs its `agentId`).
`read_workforce_thread`	read	Read a thread's messages and status (needs `agentId` + `threadId`). Pass `wait: true` to long-poll (bounded ~25s; may return still-running).
`send_to_workforce_agent`	write	Send a message to an agent by `agentId`, starting or continuing a thread.

Sending a task and reading the result

Because agent runs are asynchronous, driving one is a two-step pattern:

send_to_workforce_agent with the agentId (from list_workforce_agents) and your message. It returns a threadId.
read_workforce_thread with that agent's agentId, the threadId, and wait: true. The wait is bounded (~25 seconds): it returns the messages as soon as the run finishes, but if the run is still going it returns isRunning: true and you must call read_workforce_thread again - repeat until isRunning is false.

Skills

Read any skill available to your organization, and - on a read-and-write connection, if your account can manage skills - author your organization's custom skills without leaving your editor. Reads cover your custom skills plus the public Octavus skills; writes only ever touch your own custom skills.

Tool	Access	Description
`list_skills`	read	List the skills available to your organization (custom + public Octavus), with slug, description, version, category, and secrets.
`get_skill`	read	Read a skill's full `SKILL.md` (frontmatter + body) and its `scripts/`, `references/`, and `assets/` files, by id or slug.
`save_skill`	write	Create or update a custom skill by slug (create if new, update if it exists). Files merge by path; `replace: true` swaps them all.
`delete_skill`	write	Archive a custom skill by id or slug (soft delete; the slug is freed for reuse).

Authoring a skill

The write loop mirrors editing an agent:

fetch_documentation with the slug protocol/skills to read the SKILL.md contract (frontmatter fields, scripts, secrets).
Design the SKILL.md body and any scripts/ locally (or get_skill an existing one to edit it).
save_skill with the slug, description, body, and files. Send only the files that changed - they merge by path - or pass replace: true to replace the whole set.

save_skill can declare the secrets a skill needs (the secrets frontmatter), but it never sets secret values: those are configured per organization in the Octavus dashboard and stay UI-only.

Documentation

Read the Octavus documentation from inside your AI tool, so it can answer from the real docs instead of guessing or browsing the web. Both tools are available on any connection.

Tool	Access	Description
`search_documentation`	read	Search the docs for matching pages (slug, title, section, excerpt). Omit the query to list every page.
`fetch_documentation`	read	Fetch a full documentation page as markdown by its `slug` (from `search_documentation`).

A typical loop is two steps: search_documentation with a query to find the right page, then fetch_documentation with the returned slug to read it.