- Badges are explained under Approvals.
project_idis optional on most tools; without it, the server picks a project for that call only (Projects).expected_organization_idis an optional string on every write tool, omitted from parameter tables; passorganization.idfromget_identity(Organization check).limitvalues above a tool’s maximum are capped, not refused.
Tools
inspect_project_ai
Get built-in and custom agents, models, and Oqoqo AI settings. Returns agents, provider and model readiness, your personal connections, model refresh state, and each Oqoqo AI feature’s model and whether it can run. It never returns secrets or starts a refresh. Read-only · CLI:oqoqo project ai inspect
Result fields
The
roles, providers, agents, and models views return top-level revision (the project revision), organizationRevision, secretRevision, and editRevision fields for writes, plus agent, provider, model, and role counts, provider readiness, model refresh counts, and blockers. blockers is empty when you can run models; otherwise it says why not, with the dashboard setupUrl where a person fixes it.
A custom agent’s custom block has status (needs_values, testing, needs_attention, not_tested, or ready), description, revision, connectionId, url, definition, env, envNote, testBlockers, handshake (start-up details such as failure.message, failure.detail, and authMethods), fix (the failed step and what to change), mcpServersRefused, and latestRun. See Custom agent fields.
In the providers view, each provider’s modelRefresh has status, listedAt, and the counts of the last refresh. listedAt is set when the refresh has read the provider’s list, so the models view has those models while status is still running. See oqoqo project ai inspect.
A provider’s modelCount counts the models that an agent or an Oqoqo AI feature can use now, and enabledModelCount counts the ones of those that are turned on. unavailableModelCount counts the listed models that cannot be used with the current credentials.
In the models view of a provider, each model has availability (available or unavailable). An unavailable model also has availabilityReason (refused, credentials_changed, or not_checked) and availabilityMessage, which says the reason in a sentence. Models that cannot be used explains each reason. availability with another view or with agent_key returns invalid_request.
A cursor continues only the list it came from, so pass the same availability with it. A cursor returns stale_cursor when the configuration changed between pages, usually from a model refresh.
manage_project_ai
Create custom agents and change agents, models, and Oqoqo AI settings. Creates or changes custom agents, turns agents and models on or off, refreshes model lists, states context windows, and sets each Oqoqo AI feature’s model and instructions. No operation carries a secret. Changes data · CLI:oqoqo project ai apply
A custom agent’s
source is one of:
kind: "registry"withregistryIdand an optionalversion: an agent from the ACP Registry.kind: "manual"withinstalland optionalargs.installis an npm package (kind: "npm",package), a Python package (kind: "python",package), or a download (kind: "download",url,sha256,command).kind: "agent_json"withagentJson: anagent.jsondefinition.
env lists up to 64 environment variable names. Values are entered only in the dashboard, and the result returns the agent’s page and the dashboard link for each value. skillsFolder is the folder where the agent reads skills, up to 256 characters.
A stale revision changes nothing and returns configuration_changed, with details.currentRevision when the target has one. An invalid operation returns validation_error. Read inspect_project_ai again before you retry. When a public catalog lists a context window for a model, inspect_project_ai reports it as suggestedContextWindow, which applies only after you state it. Connecting, signing in again, switching accounts, and entering credentials stay on the provider’s dashboard link from inspect_project_ai.
delete_project_ai
Remove custom agents or provider connections. Removes a custom agent, deletes a custom provider connection, resets a built-in organization connection, or disconnects your personal provider account. Destructive · CLI:oqoqo project ai delete
A removed custom agent no longer shows in new experiments or the Agents list, and Oqoqo clears its environment variable values. Past results keep its name. Oqoqo refuses the removal while a run of the agent is in progress, either a Test agent run or an experiment. Removing it again returns the same result.
Pass the revisions from
inspect_project_ai. A refused removal changes nothing and returns one of these codes:
test_custom_agent
Test a custom agent (private beta). Checks that a custom agent installs, starts, and answers, with one run of the Agent check task: Agent default, the Raw Agent treatment (no tools), no project files, and Evals and Insights off. It uses 1 run. Changes data · You approve each call · CLI:oqoqo project ai test-agent
Poll the returned
launchId with get_launch_status. Each finished run with these settings updates the agent’s status in inspect_project_ai. A Test agent run is a check, not an experiment. It sends no notice and doesn’t show on Home or in the dashboard’s experiments list, but the CLI and the plugin still list it.
It refuses while custom.testBlockers names a blocker, with the first one’s code:
get_setup_links
Get secure setup links. Returns the dashboard links for OAuth connections, API keys, secret headers, and other secret values. Read-only · CLI:oqoqo setup links
Result fields
issues lists each machine, MCP server, CLI, and SDK in the project that still needs a required value or your account connection, with the setupUrl where a person adds it. An MCP server whose saved values aren’t bound to its current address has a field of scope address, and its setupUrl is the server’s Tools tab, where a person selects Refresh. The list is empty when nothing is missing.
inspect_mcp_account
Check your MCP server connection. Checks whether your account can use an MCP server in a treatment, and returns the latest problem, a next step, and the dashboard setup link. A failed reconnect never replaces a working connection. Read-only · CLI:oqoqo mcp accounts inspect
Result fields
ready, recovery (with message, action, setupUrl, retryAt, and apiKeyAlternative), setupUrl, redirectUri, and oauthAppConfigured. Their meanings are under oqoqo mcp accounts inspect. When the server’s saved values aren’t bound to its current address, ready is false and setupUrl is the version’s Tools tab, where a person selects Refresh.
detect_mcp_auth_mode
Detect how an MCP server authenticates. Probes the server’s current definition and reports how it authenticates. It never returns the server’s endpoint or credentials, and the OAuth app’s Client ID and Client secret are entered only in the dashboard. See MCP server sign-in. Read-only · CLI:oqoqo mcp accounts detect-auth
Result fields
list_mcp_server_tools
List an MCP server’s tools. Reads the tools the server listed at Oqoqo’s last check, with the check’sstatus, message, time, tool count, and Tools page (setupUrl). Titles, descriptions, and hints are the server’s own text.
Read-only · CLI: oqoqo mcp tools list
Continue with
after_position while truncated is true.
Result fields
The check’s status, message, and time, the tool count, setupUrl, truncated, nextAfterPosition, usageRunCount, lastChange, headerValuesBound, and each tool with canTurnOff, onRunCount, runCount, callCount, offInTreatmentCount, and offInTreatmentIds. Their meanings are under oqoqo mcp tools list.
When headerValuesBound is false, only a person’s Refresh at setupUrl binds the saved values: refresh_mcp_server_tools fails with mcp_tool_check_needs_web and launches stop with mcp_header_values_unbound. Give the person setupUrl instead of calling it (Saved header values and the server address).
refresh_mcp_server_tools
Refresh an MCP server’s tools. Checks the server’s tools now and returns the list aslist_mcp_server_tools does. A running check is joined, not restarted. A server that needs your account connection or a header value returns that status and its setupUrl.
Changes data · CLI: oqoqo mcp tools refresh
Result fields
The fields of
list_mcp_server_tools, plus refresh, which is running until the check finishes. If the wait ends first, read the list again with list_mcp_server_tools.
It never sends saved header values to an address they aren’t bound to, and it never binds them. When headerValuesBound is false, it fails with mcp_tool_check_needs_web. Give the person details.setupUrl (the version’s Tools tab) to check the address and select Refresh, and don’t call the tool again until they have.
list_github_repositories
List GitHub accounts and repositories for Ask Oqo (private beta). Lists the GitHub accounts you can access, each with its default project, and every repository that has a project of its own, for Ask Oqo in GitHub (CI/CD). Withinstallation_id, it lists one connected account’s repositories from GitHub.
Read-only · CLI: oqoqo github repos list
Result fields
The person installs the app and chooses its repositories on GitHub, at
installUrl and an account’s settingsUrl. Only the person can open those pages. A comment must mention the app, @ followed by appSlug, for Ask Oqo to answer. Without a GitHub connection, the tool returns github_connection_required, and details.connectUrl is the dashboard page where the person connects GitHub.
manage_github_repository
Connect a GitHub account or choose a repository’s project (private beta). Connects a GitHub account to the organization, sets an account’s default project, or chooses one repository’s project. The result has the same fields aslist_github_repositories.
Changes data · You approve each call · CLI: oqoqo github accounts connect, oqoqo github accounts default-project, oqoqo github repos link, oqoqo github repos unlink, oqoqo github accounts link-me
Repeating an operation changes nothing. The tool can’t install the app or change which repositories it can read. A refused call changes nothing and returns one of these codes:
disconnect_github_account
Disconnect a GitHub account from Ask Oqo (private beta). Disconnects a GitHub account from the organization. Ask Oqo stops answering in all of its repositories, and the account’s default project and its repositories’ projects are removed. The app stays installed on GitHub, and connecting the account again doesn’t bring the projects back. Destructive · CLI:oqoqo github accounts disconnect
The result lists the accounts and repositories that remain.
Related
oqoqo project ai and setup
The matching CLI commands.
Custom agents
Add and test ACP custom agents.

