What can you do with this server?

The Opik MCP Server is a Model Context Protocol implementation that provides a unified interface for managing Opik resources through various transport mechanisms: * Prompt Management: Create, list, update, delete prompts, and manage versions * Project/Workspace Management: Create, list, update, and delete projects * Trace Management: List traces, retrieve details, and access statistics * Metrics: Query metrics data with filtering options * Server Information: Retrieve configuration details * Contextual Help: Access help topics and examples

Which integrations are available for this server?

Used for configuration through environment variables in a .env file Hosts the repository and provides licensing information Provides a Makefile for common operations like testing and starting the server Used as the runtime environment for the MCP server Implements pre-commit hooks to ensure code quality Provides community support through the linked Slack community Provides TypeScript language support for the MCP server implementation

How do I use Opik MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Opik MCP Server list my recent prompts" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

Opik MCP Server

by comet-ml

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Opik MCP Server

The official Model Context Protocol (MCP) server for Opik, the open-source LLM observability and evaluation platform, built by Comet. Plug your AI host (Claude Code, Cursor, VS Code Copilot, Codex, opencode, or any MCP client) directly into your Opik workspace: read traces, log scores, and save prompt versions, all from the chat.

Built for LLM engineers who already run Opik and want to drive it from the same AI assistant they code with.

Migrating from the old npx opik-mcp? The TypeScript server is deprecated and sunsets on 2026-11-15. Swap npx -y opik-mcp for uvx opik-mcp@latest in your MCP client config. Full guide: legacy/typescript/MIGRATION.md.

You:    "Which traces in project 'demo' failed today?"
Claude: → list(entity_type="trace", project_name="demo") → "Three traces failed…"

You:    "Score trace 7f2e… 0.9 on helpfulness with reason 'great recovery'."
Claude: → write(score.create) → done

Quick start

One command registers the server with the AI clients on your machine, installs the Opik skill pack, and verifies the connection. It needs uv and no Opik SDK:

uvx opik mcp configure

It detects Claude Code, Cursor, VS Code Copilot, Codex and opencode, and uses the hosted server on Opik Cloud (browser sign-in, no API key stored) or this local server elsewhere. Any other MCP client can take the hosted URL directly:

npx add-mcp https://www.comet.com/opik/api/v1/mcp --name opik-mcp

Add to Cursor Install in VS Code

Setup guide, troubleshooting and FAQ: comet.com/docs/opik/mcp-server. The rest of this README covers the local server, which the command above sets up for self-hosted and open-source Opik, and which you can also configure by hand.

Related MCP server: dap-mcp

Manual install

opik-mcp is a Python package (requires Python 3.13+). The recommended way to run it is uvx, which fetches and runs the latest published version on demand — no global install, no virtualenv juggling.

Install uv once:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# or: brew install uv

You'll need two things from your Opik workspace:

OPIK_API_KEY — get it from comet.com/api/my/settings/.
OPIK_WORKSPACE — your workspace name (lowercase, as it appears in the URL). E.g. https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai. COMET_WORKSPACE is accepted as a deprecated alias.

Cloud, with an API key: set it unless your account default is the one you want. Left out, the server sends default, which Comet resolves to your account's default workspace. That works, but if you actually work in a named workspace you will be pointed at a different one with nothing to tell you — your reads come back from the wrong place rather than failing.
Cloud, over OAuth: leave it unset. The workspace comes from the token you authorized, and the server ignores this setting entirely.
Local / open source: leave it unset. Open source Opik has a single workspace named default and no way to create others, which is exactly what the fallback gives you.
Self-hosted Comet: set it. Unlike open source, these deployments have real named workspaces, and the same silent-wrong-workspace risk applies.
Whichever applies, make sure the value is actually substituted. Snippets in the wild ship placeholders like <your-workspace> or ${input:OPIK_WORKSPACE}; pasted as-is, those are not workspace names. The server now refuses them outright rather than letting the backend answer with an auth error that explains nothing.

Claude Code

Add the server with one command:

claude mcp add --transport stdio opik-mcp \
  --env OPIK_API_KEY=<your-key> \
  --env OPIK_WORKSPACE=<your-workspace> \
  -- uvx opik-mcp

Or edit ~/.claude.json directly:

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

Restart Claude Code. Verify with /mcp — opik-mcp should appear as connected. Then, in the chat, ask: "list my Opik projects" — Claude will call the list tool and you'll see your workspace's projects.

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project), or open Cmd+Shift+J → Features → Model Context Protocol:

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

Reload Cursor; the green dot next to opik-mcp in the MCP panel confirms the connection. Ask in chat: "list my Opik projects".

Cursor 60s timeout. Cursor enforces a hard tool-call timeout that doesn't reset on progress notifications. See Known host limits.

VS Code Copilot

.vscode/mcp.json in your workspace (or User Settings JSON):

{
  "servers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

Reload the window; the Copilot Chat MCP indicator shows opik-mcp once the server is reachable. Ask in chat: "list my Opik projects".

MCP Inspector (manual testing)

OPIK_API_KEY=<your-key> OPIK_WORKSPACE=<your-workspace> \
  npx @modelcontextprotocol/inspector uvx opik-mcp

Self-hosted Opik

Add COMET_URL_OVERRIDE (and OPIK_URL if Opik lives at a non-default path) to the same env block in your host config:

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>",
        "COMET_URL_OVERRIDE": "https://opik.your-company.com",
        "OPIK_MCP_ANALYTICS_SOURCE": ""
      }
    }
  }
}

Omit OPIK_WORKSPACE on an open-source deployment, where default is the only workspace; keep it on a self-hosted Comet, which has real named ones.

Setting OPIK_MCP_ANALYTICS_SOURCE="" opts your install out of the cloud-Comet source label on telemetry events.

Tools

opik-mcp exposes a small, outcome-oriented surface that covers the full lifecycle (read → annotate → curate → author → iterate).

Tool	Purpose
`read`	Universal read by id / name / `opik://` URI
`list`	Universal list with optional name filter + pagination
`write`	Universal write — log traces/spans, score, comment, save prompts, manage test suites & experiments
`schema`	Introspect write-operation schemas (used by the LLM to construct valid payloads)
`read_skill`	Read one of the Opik agent skills bundled with this server

`read`

One tool for any "show me X" question. Takes an entity_type plus an id (UUID or, for nameable types, a name) or a full opik:// URI. Composite reads (trace, prompt, thread, agent_insights_issue) inline their children so a single call returns the full picture.

The record you name comes back whole. Inlined children do not: their bodies are fetched with the backend's truncate=true, so a field over ~10 KB is cut in ClickHouse and base64 images are replaced with "[image]" — one attachment echoed across 200 spans would otherwise cost more than everything else in the read. The answer says so in spanBodies / messageBodies, and any child is whole again through its own read("span", id) or read("trace", trace_id), which hit endpoints that have no truncate parameter at all.

An inlined collection is also bounded in length: 200 spans, 200 turns, 100 prompt versions. Past that, spansTruncated / messagesTruncated / versionsTruncated is true and a moreSpans / moreMessages / moreVersions line beside it carries the count and the exact list(...) call that continues from where the inlined part stopped.

Supported entities: project, trace, span, test_suite, experiment, prompt, thread, agent_insights_issue. Name-based lookup is available for project, experiment, prompt, test_suite (slower — two API calls — and may return multiple matches). thread and agent_insights_issue are project-scoped: pass project_id or project_name, or a link/URI that carries the project.

read(entity_type="trace", id="7f2e3c8a-…")
read(entity_type="project", id="demo")          # name lookup
read(entity_type="trace", id="opik://traces/7f2e3c8a-…")
read(entity_type="agent_insights_issue", id="<issue-uuid>", project_id="<project-uuid>")
read(entity_type="agent_insights_issue", id="https://www.comet.com/opik/<ws>/projects/<pid>/diagnostics?issue=<id>")

A link copied from the Opik UI works as the id: a thread link or a Diagnostics page link carries the project, so no project_id is needed and the entity type is taken from the link.

A project read answers "how is my project doing" in one call. It returns {project, summary, vocabulary, contains, url}: the record, then the four figures the Logs page shows as cards (trace count, error rate, average duration, total cost) for the last 7 days against the 7 before, SDK traffic only, as on screen. since / until move that window; since="30d" is what the UI opens on. A rate or an average over a period with no traces comes back as null, because 0% errors on a week with no traffic reads as a healthy week.

vocabulary is the map you need before you can ask anything else: the project's feedback score names, its token usage keys, and the automation rules scoring its traces. These are the names that go into a filter or into series= below, and guessing them returns an empty page that reads like good news. Score names and rules are capped, always report the true total, and name the call that returns the rest; usage keys are listed in full, since nothing else enumerates them. contains names the freshest experiment, test suite, prompt version and optimization run, so "what has been happening here" does not need four more calls. A part that failed to load says so instead of looking empty, and an empty one is omitted.

An agent_insights_issue read returns {issue, example_trace_ids, details}: the Diagnostics issue record (name, description, cause, suggested fix, severity, status), the deduplicated ids of the traces that exhibit it (the same sample the Diagnostics page shows — open one with read("trace", id)), and the per-day breakdown. Trace bodies are not inlined, so the read stays one backend call. since / until narrow the per-day rows; the default is all-time. When the server knows the Opik URL and the session's workspace, the read also carries url (the issue's Diagnostics page) and trace_url_template (a deep link for any of the example traces), so the assistant can hand you something clickable; under an OAuth session whose workspace could not be resolved the links are omitted rather than guessed.

Traces themselves carry no URL — a link for one is not derivable from the fields a read or list returns, and a guessed shape 404s. The session instructions name a template for it instead, .../v1/session/redirect/projects/?trace_id={trace_id}&path=..., so the assistant fills in an id and hands you a link. It goes through opik-backend's redirect, which resolves the project and the workspace from the trace, so it works where a direct project URL cannot, an OAuth session with an unresolved workspace included. It is the same link the Python SDK prints for a trace.

`list`

Browse or search a collection with pagination. Project-scoped types (trace, span, thread, agent_insights_issue, test_suite_item, prompt_version) need their parent: a project UUID or name, a suite UUID, or a prompt UUID.

list(entity_type="experiment", page=1, size=25)
list(entity_type="experiment", name="rerank")          # name substring filter
list(entity_type="agent_insights_issue", project_name="demo")             # open Diagnostics issues
list(entity_type="agent_insights_issue", project_id="<uuid>", status="resolved")
list(entity_type="trace", project_name="demo")         # latest traces of one project
list(entity_type="trace", project_name="demo",
     filters='error_info is_not_empty AND duration > 5000')
list(entity_type="span", project_name="demo",          # spans across the whole project
     filters='type = "llm" AND usage.total_tokens > 10000')
list(entity_type="thread", project_name="demo",
     filters='number_of_messages > 20 AND feedback_scores.helpfulness < 0.5')
list(entity_type="experiment",
     filters='dataset_id = "<dataset-uuid>" AND tags contains "baseline"')

Filters. trace, span, thread and experiment take an OQL string, the same grammar as the SDK's search_traces(filter_string=…):

<field>[.<key>] <op> <value> [AND ...]
ops: = != > >= < <= contains not_contains starts_with ends_with is_empty is_not_empty in not_in

Strings go in double quotes, numbers are bare, duration is in milliseconds, dates are ISO-8601 instants with a timezone ("2026-09-08T10:00:00Z"). Scores and dictionaries take a key: feedback_scores.accuracy < 0.5, metadata.environment = "prod". AND is the only connector.

Like the UI's Logs page, trace, span and thread lists add source = "sdk" so evaluator, playground and experiment traces stay out of the way; name source yourself to see them. The first output line echoes the filter that was applied.

A bad filter fails before reaching the backend with what is needed to fix it: the position of a syntax error, the closest field name, the valid operators for the field's type, or the expected value format. Fields with a closed set of values (source, span type, thread status, visibility_mode) are checked against it too, every element of an in list included. source is the one the backend validates itself, and it answers an unknown value with a 500 rather than a 400, so source = "SDK" would otherwise be an opaque server error for a capital letter. The rest are compared as strings and answer with an empty page, which reads as "no matches" when it means "no such value". Ask schema("list.trace") (or list.span, list.thread, list.experiment) for the full field reference, accepted values included.

Sort. The same four types take sort="<field> [asc|desc]", desc by default and one field only: sort="duration desc", sort="total_estimated_cost", sort="feedback_scores.accuracy asc", sort="usage.total_tokens". The field is checked against the entity's sortable list before the call, because the backend silently ignores fields it cannot sort by. On very large workspaces the backend drops sorting altogether; the header says so when that happens.

Time window and search. trace, span and thread take since and until, each a relative span ("30m", "1h", "7d") or an ISO-8601 instant with a timezone, so "the last hour" needs no clock arithmetic. The window is by record creation time, which is cheap for the backend and agrees with start_time within seconds for live traffic. For an exact bound, put start_time in filters. The same three types take search, free text matched anywhere in id, name, input, output, metadata, tags and thread id. Search scans the whole project on the backend, so the first call on a large project can take tens of seconds. Those calls get a 60-second timeout. Adding since makes them fast again.

Reading the table. Durations are labelled duration_ms / ttft_ms and shown as whole milliseconds; the field stays duration in filters and sort. Timestamps are shown to the second and costs as plain decimals. Project rows carry last_updated_trace_at so you can see which project has live traffic; thread rows carry the first message. An empty page under a time window says when the project's last trace landed, and an empty page under the default source = "sdk" says how to see the other sources. A misspelled project_name comes back with the closest existing name.

list(entity_type="trace", project_name="demo", since="1h",
     filters="error_info is_not_empty", sort="duration desc")
list(entity_type="trace", project_name="demo", search="order-42")

Diagnostics issues. agent_insights_issue is the Diagnostics page over the MCP: the recurring failures Opik's Diagnostics job grouped for a project, ranked as the UI ranks them (most recently seen first). Columns are severity, status, total_occurrences (all-time sum), latest_count (the most recent report day, the number the issue's own description refers to) and last_seen. Open issues are listed by default; pass status="resolved" or "closed" for the rest. read and list also answer to issue, which is what the UI calls these; the long name is the one in the entity_type enum, so that one entity does not appear there twice. Counts are all-time so they match the UI; the same since / until as for traces narrow the window, truncated to UTC report days because Diagnostics aggregates per day.

An empty list says why it is empty, because "nothing is broken" and "nobody turned Diagnostics on" read the same otherwise. There are five states: Diagnostics is unavailable on this deployment, not enabled for this project, turned off, enabled but not scanned recently, or enabled and clean with the time of the last scan. The ones you can act on name the call to make, and every state links the project's Diagnostics page.

A non-empty list dates itself. The issues are whatever the last scan grouped, so the reply ends with Report covers data through <time>, and when the window you asked about runs past that, it names the uncovered tail and how to close it: a trigger when a rescan reaches back far enough, otherwise raw traces with the since it gives you. Ask for a week on a project scanned nightly and the last day is missing from the grouped answer; this is what says so.

write("agent_insights_job.enable", {"project_name": "demo"}) turns Diagnostics on. It scans daily from then on, and calling it again is safe. write("agent_insights_job.trigger", …) scans the last 24 hours now, without waiting for the nightly run. Both take the permission that reading issues takes, and both refuse where the deployment has no Diagnostics.

An issue moves through its lifecycle with write("agent_insights_issue.resolve", {"issue_id": "<uuid>", "project_name": "demo"}) — dealt with — or …close for one not worth acting on, and …reopen to put either back on the open list. All three take the same permission and answer with a link to the view the issue moved to, since a resolved issue is no longer on the default page. Whether a failure is fixed is a judgment call, so these are for when you ask: the assistant has no business tidying the list while triaging it.

Metrics over time. project_metric charts one metric for a project as a table of time buckets: trace, span and thread counts, durations, error rates, costs, token usage and feedback scores. It answers the question that follows the overview, which is when something changed.

list(entity_type="project_metric", project_name="demo", metric_type="trace_count")
list(entity_type="project_metric", project_name="demo", metric_type="trace_error_rate",
     since="14d", interval="daily")
list(entity_type="project_metric", project_name="demo", metric_type="span_count",
     breakdown="model")                      # one column per model
list(entity_type="project_metric", project_name="demo", metric_type="span_duration",
     breakdown="model", series="p99")        # the p99 of each model

Rows are time buckets, not records, so page, size and sort are refused rather than ignored. interval is hourly, daily, weekly or total; left out, it follows the window the way the Metrics tab does — hourly up to 3 days, daily up to 30, weekly beyond — so a default chart is a few dozen rows whatever the range, and an hourly month (721 rows) is something you ask for. since / until take the same forms as everywhere else and default to the last 7 days. filters uses the fields of whichever entity the metric is about, so a span metric is filtered by span fields.

breakdown splits each bucket by tags, name, error_info, error_type, model, provider, span_type, guardrail_name or metadata.<key>. Not every metric accepts every one of those, and seven accept none at all; the tool knows which and says so before calling the backend, naming a metric that does answer the same question where one exists. Three families come back as several series at once (a duration as p50/p90/p99, a feedback score per name, token usage per key), and the backend charts one of them at a time when grouping, so series= picks it: a percentile, a score name, or a usage key. Duration defaults to p50 and token usage to total_tokens, and whichever was used is echoed on the first line.

Empty buckets are left out and counted underneath, so a quiet month is a few rows instead of a column of zeros, and a rate over a bucket with no traces is absent rather than reported as zero.

Ask schema("list.project_metric") for the metric table, the intervals and the per-metric grouping matrix.

A project's names. score_name lists the feedback score names recorded in a project and online_rule the automation rule evaluators configured on it, which is where most of those names come from. Both are the same lists read("project", …) carries, in full and paginated, for when the capped version in the overview is not enough.

list(entity_type="score_name", project_name="demo")
list(entity_type="online_rule", project_name="demo")

`write`

Universal write dispatcher. Pass operation + data and the dispatcher validates the payload, applies the right REST verb, and returns the backend response.

Operations:

Operation	What it does
`trace.create`	Log a single trace (or a batch). Parent for spans / scores / comments.
`trace.update`	Finalize or amend an existing trace.
`span.create`	Log a span on an existing trace (or a batch).
`score.create`	Attach a numeric feedback score to a trace, span, or thread.
`comment.create`	Attach a free-text comment to a trace, span, or thread.
`prompt_version.save`	Save a new prompt version (creates the prompt by name if missing).
`test_suite.create`	Create an evaluation test suite.
`test_suite_item.upsert`	Upsert items into a test suite (always the envelope shape).
`experiment.create`	Create an experiment scoped to a test suite.
`experiment_item.create`	Attach trace + dataset_item rows to an experiment.
`agent_insights_job.enable`	Turn Diagnostics on for a project (daily scans, safe to repeat).
`agent_insights_job.trigger`	Run a Diagnostics scan now, over the last 24 hours.
`agent_insights_issue.resolve`	Mark a Diagnostics issue dealt with (ask the user first).
`agent_insights_issue.close`	Mark a Diagnostics issue not worth acting on (ask the user first).
`agent_insights_issue.reopen`	Put a resolved or closed Diagnostics issue back on the open list.

write(operation="score.create", data={
  "target": "trace",
  "target_id": "7f2e3c8a-…",
  "name": "helpfulness",
  "value": 0.9,
  "reason": "great recovery"
})

`schema`

Inspect the exact JSON shape and required fields of any write operation before you call it — useful when you're not sure what data should look like. Returns the schema, OAuth scope, and one validated example. Pure lookup, no backend call.

schema(operation="score.create")
schema(operation="prompt_version.save")

The same tool answers list.trace, list.span, list.thread and list.experiment with the list tool's reference for that entity: every filterable field with its type and valid operators, the sortable fields, whether a time window and free-text search apply, and two example filters.

schema(operation="list.trace")

Configuration

Every setting is an environment variable. Required ones in bold.

Identity / endpoint

Variable	Default	Notes
`OPIK_API_KEY`	—	Required for any authenticated read/write.
`OPIK_WORKSPACE`	unset	Workspace name. On cloud with an API key, unset sends `default`, which resolves to your account's default workspace — set it explicitly if you work in a different one, or reads come from the wrong workspace silently. Leave unset over OAuth (the token carries it) and on local/OSS (`default` is the only workspace there).
`COMET_WORKSPACE`	—	Deprecated alias for `OPIK_WORKSPACE` (backward compat). `OPIK_WORKSPACE` wins if both are set.
`COMET_WORKSPACE_ID`	unset	Optional workspace UUID. Stamped into analytics events when set, and takes precedence over the resolved one. Rarely needed — OAuth installs get the UUID from the token automatically.
`COMET_URL_OVERRIDE`	`https://www.comet.com`	Set to your self-hosted Comet host, or `https://dev.comet.com` for staging.
`OPIK_URL`	derived from `COMET_URL_OVERRIDE` + `/opik/api`	Override only if Opik lives on a different host/path than the Comet UI.
`OPIK_DEFAULT_PROJECT_NAME`	unset	When set, the per-session `instructions` blob tells the LLM to pass this as `project_name` on every tool call unless the user names a different project.

Server / transport

Variable	Default	Notes
`OPIK_MCP_TRANSPORT`	`stdio`	`stdio` for host-launched, `streamable-http` to listen on a port.
`OPIK_MCP_HOST`	`127.0.0.1`	uvicorn bind host (`streamable-http` only).
`OPIK_MCP_PORT`	`8080`	uvicorn bind port (`streamable-http` only).
`OPIK_MCP_RELOAD`	`false`	`true` to enable uvicorn `--reload` (dev only).
`OPIK_MCP_AS_URL`	unset	OAuth Authorization Server URL, advertised in `/.well-known/oauth-protected-resource` (RFC 9728) and used as the proxy target for AS-discovery probes. Required for MCP hosts to bootstrap the OAuth dance over HTTP.
`OPIK_MCP_RESOURCE_URI`	unset	Canonical public URI of this server, advertised as `resource` in the protected-resource metadata and used to derive the `WWW-Authenticate` hint.
`OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S`	`30`	How long a "valid" answer from opik-backend's token introspection is trusted before the next request on the same OAuth token asks again. Bounds the backend load added by per-request validation and the window in which an expired token is still forwarded (that window also ends on the first 401 the backend returns). Capped by the token's own `expires_at` when the backend reports one.
`OPIK_MCP_LOG_LEVEL`	`INFO`	stderr logger threshold.

Choosing a transport

Two bearer shapes, two contracts on HTTP transport. An opik_mcp_at_… OAuth access token is validated on every request against opik-backend's token introspection endpoint (cached, see OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S); an expired or revoked token gets an HTTP 401 with WWW-Authenticate: Bearer error="invalid_token", which is what MCP hosts key their silent refresh_token grant on. An Opik API key is not validated locally: it is forwarded verbatim to opik-backend, which is its single point of enforcement. Pick the transport by deployment shape:

Scenario	Transport
MCP client and Opik on the same machine (local OSS install)	stdio (recommended — simplest, no port, no OAuth setup)
Local MCP client → remote Opik (Comet cloud / self-hosted)	stdio with `OPIK_API_KEY`, or HTTP with OAuth (`OPIK_MCP_AS_URL` pointing at the backend)
Hosted opik-mcp behind the same edge as opik-backend	HTTP — bearers are validated by the backend per request

Note for local OSS installs: the OSS backend does not authenticate requests, so an HTTP opik-mcp in front of it is as open as the OSS REST API itself. Keep the default 127.0.0.1 bind (and prefer stdio) on shared networks.

Telemetry

Anonymous usage events (event type + timing only — no query content). A SHA-256 digest of your API key is included so support can find your account; the raw key never leaves the process. Opt out: OPIK_MCP_ANALYTICS_ENABLED=false.

Variable	Default	Notes
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Set to `false` to disable all telemetry.
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	Override for staging.
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	Tag on every event (`prod` / `staging` / `dev`).
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	Receiver uses this to mark `on_prem=False`. On-prem installs should override to `""` or their own domain.
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	HTTP connect timeout.
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	HTTP total request timeout.

Known host limits

Hosts differ in how long they let a single tool call run:

Claude Code — no documented tool-call timeout. Recommended.
Cursor — hard 60s timeout that does not reset on progress (upstream bug).
MCP Inspector — MAX_TOTAL_TIMEOUT bounds total duration (default 60s). Raise it in the Inspector UI for long operations.

If a call gets stuck, set OPIK_MCP_LOG_LEVEL=DEBUG for the full request log.

Troubleshooting

OPIK_API_KEY isn't picked up — the var isn't reaching the server process. In Claude Code / Cursor / VS Code, env vars only apply when inside the env block of the MCP server config, not your shell. Restart the host after editing.

Cursor call times out at 60s — Cursor's known bug, not opik-mcp. Either narrow the call (smaller size, a tighter window), or run the same operation on Claude Code which has no hard cap.

Server not showing, sign-in not opening, wrong workspace, uvx not found. These are covered in the troubleshooting section of the docs. opik mcp status (from the same uvx opik CLI) lists every client that has the server configured and whether its config has drifted.

Development

git clone git@github.com:comet-ml/opik-mcp.git
cd opik-mcp
make install        # uv sync --extra dev
make check          # lint + typecheck + test
make run-dev        # uvicorn with --reload + DEBUG logs
make inspect        # MCP Inspector against the running server

Common targets:

Target	What it does
`make install`	`uv sync --extra dev`
`make run`	Run the MCP server (stdio by default).
`make run-dev`	Run with DEBUG logging + uvicorn `--reload`.
`make dev`	Run via `mcp dev` (Inspector dev-mode wrapper).
`make inspect`	Launch MCP Inspector against a running server.
`make test`	`uv run pytest -q`.
`make lint`	`ruff check` + format check.
`make format`	`ruff format` + `ruff check --fix`.
`make typecheck`	`mypy`.
`make check`	`lint + typecheck + test`.

Repo layout:

opik-mcp/
├── src/opik_mcp/        ← server, tools, analytics
├── tests/               ← pytest suites
├── scripts/             ← live-BE smoke + MCP-session smoke
├── legacy/typescript/   ← deprecated v2 TS server
├── pyproject.toml
└── Makefile

Get help

Open an issue for bugs and feature requests
Opik docs for SDK / backend documentation
Comet community Slack for questions

Upgrading from v2? The legacy TypeScript server still ships on npm as opik-mcp@^2 (npx -y opik-mcp); source is preserved under legacy/typescript/. See legacy/typescript/DEPRECATED.md for the support policy.

License

Apache-2.0.

Available Tools

19 tools

create-projectC

Create a new project/workspace

ParametersJSON Schema

Name	Required	Description
`description`	No	Description of the project
`name`	Yes	Name of the project
`workspaceName`	No	Workspace name to use instead of the default

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Create') but doesn't cover critical aspects like required permissions, whether the creation is idempotent, what happens on conflicts, or the expected response format. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

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 a single, efficient sentence with zero wasted words—it directly states the tool's purpose without unnecessary elaboration. It's appropriately sized and front-loaded, making it easy to parse quickly.

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

Completeness2/5

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

Given that this is a mutation tool ('Create') with no annotations and no output schema, the description is insufficient. It doesn't explain what a 'project' or 'workspace' entails in this system, how to handle errors, or what the tool returns upon success, leaving the agent with incomplete context for effective use.

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?

The description adds no parameter-specific information beyond what's already in the input schema, which has 100% coverage with clear descriptions for all three parameters. This meets the baseline of 3, as the schema adequately documents the parameters, but the description doesn't provide additional context like examples or usage notes.

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?

The description 'Create a new project/workspace' clearly states the verb ('Create') and resource ('project/workspace'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'create-prompt' or explain what differentiates a 'project' from a 'workspace' in this context, which prevents a perfect score.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives like 'update-project' or 'list-projects', nor does it mention prerequisites or constraints. While the verb 'Create' implies it's for new entities, there's no explicit comparison to siblings or context for usage decisions.

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

create-promptC

Create a new prompt

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes	Name of the prompt

TDQS

C2.3/5.0

Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure. 'Create a new prompt' implies a write/mutation operation but provides no details about permissions needed, whether creation is idempotent, what happens on conflicts, or what the response contains. This leaves significant behavioral gaps for a creation tool.

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 extremely concise at just three words. While it's under-specified in content, it's not verbose or poorly structured. Every word earns its place in this minimal description.

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

Completeness2/5

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

For a creation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what a 'prompt' is in this context, what fields beyond 'name' might be set by default, what the creation response looks like, or how this differs from similar tools. The description fails to provide necessary context for effective tool use.

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 the single 'name' parameter. The description adds no additional parameter context beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no parameter information in the description.

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

Purpose2/5

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

The description 'Create a new prompt' is a tautology that restates the tool name without adding specificity. It doesn't distinguish this tool from sibling tools like 'create-prompt-version' or explain what kind of prompt is being created. The purpose is minimally stated but lacks meaningful differentiation.

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

Usage Guidelines1/5

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

No guidance is provided about when to use this tool versus alternatives like 'create-prompt-version' or 'update-prompt'. There's no mention of prerequisites, constraints, or appropriate contexts for invoking this creation tool versus other prompt-related operations.

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

create-prompt-versionC

Create a new version of a prompt

ParametersJSON Schema

Name	Required	Description
`commit_message`	Yes	Commit message for the prompt version
`name`	Yes	Name of the original prompt
`template`	Yes	Template content for the prompt version

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool creates a new version but doesn't explain what that entails—whether it's a write operation, requires specific permissions, affects existing prompts, or has side effects like triggering notifications. For a mutation tool with zero annotation coverage, this lack of detail is a significant gap in transparency.

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 a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action ('Create a new version'), making it easy to parse quickly. Every word earns its place, and there's no redundancy or fluff.

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

Completeness2/5

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

Given the complexity of a versioning operation (a mutation with potential side effects), no annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions, idempotency, or error handling, nor does it hint at return values. For a tool that modifies data, this leaves critical gaps for an AI agent to understand its full context.

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 fully documents the three parameters (name, template, commit_message). The description adds no additional meaning beyond what's in the schema, such as explaining how 'name' relates to the original prompt or what 'commit_message' is used for. With high schema coverage, a baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't need to.

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?

The description clearly states the action ('Create') and resource ('new version of a prompt'), making the purpose immediately understandable. It distinguishes from siblings like 'create-prompt' (which creates a new prompt rather than a version) and 'update-prompt' (which might modify an existing prompt without versioning). However, it doesn't specify what constitutes a 'version' (e.g., whether it's a snapshot, revision, or branch), leaving some ambiguity.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing prompt), compare to siblings like 'update-prompt' or 'create-prompt', or indicate scenarios where versioning is appropriate (e.g., for tracking changes, experimentation, or deployment). Without this, users must infer usage from the tool name alone.

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

delete-projectC

Delete a project

ParametersJSON Schema

Name	Required	Description	Default
`projectId`	Yes	ID of the project to delete
`workspaceName`	No	Workspace name to use instead of the default

TDQS

C2.1/5.0

Behavior1/5

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

With no annotations provided, the description carries full burden but discloses nothing beyond the basic action. It fails to address critical behavioral traits: whether deletion is permanent or reversible, required permissions, side effects (e.g., on associated data), error conditions, or response format. For a destructive operation, this lack of transparency is severe.

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 extremely concise with a single sentence, 'Delete a project', which is front-loaded and wastes no words. While under-specified, it efficiently communicates the core action without redundancy or fluff.

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

Completeness2/5

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

Given the tool's complexity (destructive operation with 2 parameters), lack of annotations, and no output schema, the description is incomplete. It does not compensate for missing behavioral context, usage guidelines, or output expectations, leaving significant gaps for an AI agent to understand and invoke the tool safely.

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%, with clear parameter documentation in the schema itself. The description adds no parameter semantics beyond what the schema provides, such as explaining 'projectId' format or 'workspaceName' usage. However, the baseline score of 3 is appropriate since the schema adequately covers parameters.

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

Purpose2/5

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

The description 'Delete a project' is a tautology that restates the tool name without adding meaningful context. It specifies the verb 'Delete' and resource 'project', but lacks distinction from sibling tools like 'delete-prompt' or details about what deletion entails. This minimal statement fails to clarify scope or differentiate from alternatives.

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

Usage Guidelines1/5

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

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites (e.g., project existence), exclusions (e.g., irreversible effects), or comparisons to sibling tools like 'update-project' or 'list-projects'. The description offers no context for decision-making.

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

delete-promptC

Delete a prompt

ParametersJSON Schema

Name	Required	Description	Default
`promptId`	Yes	ID of the prompt to delete

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action is destructive ('Delete') but doesn't elaborate on consequences (e.g., permanent deletion, no undo), permissions required, or error conditions. This is a significant gap for a mutation tool with zero annotation coverage.

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 extremely concise at three words, front-loading the essential action and resource without any wasted text. Every word earns its place, making it easy to parse quickly.

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

Completeness2/5

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

Given the tool's destructive nature, no annotations, and no output schema, the description is incomplete. It lacks critical information about behavioral traits (e.g., irreversibility), error handling, or what happens post-deletion. For a deletion tool, this leaves significant gaps in understanding.

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?

The description adds no parameter semantics beyond what the schema provides. Since schema description coverage is 100% (the 'promptId' parameter is fully documented in the schema), the baseline score is 3. The description doesn't compensate with additional context like format examples or constraints.

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?

The description clearly states the action ('Delete') and the resource ('a prompt'), making the tool's purpose immediately understandable. It distinguishes itself from siblings like 'delete-project' by specifying the resource type, though it doesn't explicitly contrast with other deletion tools. The description avoids tautology by not merely restating the name.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a prompt ID), exclusions (e.g., cannot delete if in use), or sibling tools like 'delete-project' for different resources. Usage is implied by the action but lacks explicit context.

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

get-metricsC

Get metrics data

ParametersJSON Schema

Name	Required	Description
`endDate`	No	End date in ISO format (YYYY-MM-DD)
`metricName`	No	Optional metric name to filter
`projectId`	No	Optional project ID to filter metrics
`projectName`	No	Optional project name to filter metrics
`startDate`	No	Start date in ISO format (YYYY-MM-DD)

TDQS

C2/5.0

Behavior1/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure but fails completely. 'Get metrics data' reveals nothing about whether this is a read-only operation, whether it requires authentication, what rate limits might apply, what format the data returns in, or any other behavioral characteristics. For a data retrieval tool with zero annotation coverage, this is a critical gap that leaves the agent with no understanding of how the tool behaves.

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 extremely concise at just three words. While this represents severe under-specification in terms of content, from a pure conciseness perspective it contains zero wasted words and is front-loaded with the core action. Every word earns its place, even though that place is inadequate for proper tool understanding.

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

Completeness1/5

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

Given a 5-parameter tool with no annotations and no output schema, the description 'Get metrics data' is completely inadequate. It provides no information about what metrics are available, what system they come from, what the return format looks like, or any behavioral characteristics. For a data retrieval tool of this complexity, the description fails to provide the minimal contextual information needed for an agent to use it effectively.

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?

The schema description coverage is 100%, meaning all 5 parameters are well-documented in the input schema itself. The description adds absolutely no additional parameter information beyond what's already in the schema. According to the scoring rules, when schema coverage is high (>80%), the baseline score is 3 even with no parameter information in the description, which applies here.

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

Purpose2/5

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

The description 'Get metrics data' is a tautology that essentially restates the tool name 'get-metrics'. It provides no specific information about what kind of metrics, from what system, or what scope. While it includes a verb ('Get') and resource ('metrics data'), it lacks any distinguishing details that would help differentiate it from potential sibling tools or clarify its specific function beyond the obvious.

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

Usage Guidelines1/5

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

The description provides absolutely no guidance on when to use this tool versus alternatives. There are no mentions of prerequisites, appropriate contexts, or comparisons to sibling tools like 'get-trace-stats' or 'get-trace-by-id' that might handle similar data. The agent receives no help in determining when this specific metrics retrieval tool is appropriate versus other data-fetching tools in the server.

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

get-opik-examplesC

Get examples of how to use Opik Comet's API for specific tasks

ParametersJSON Schema

Name	Required	Description	Default
`task`	Yes	The task to get examples for (e.g., 'create prompt', 'analyze traces', 'monitor costs')

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves examples but doesn't describe what the output looks like (e.g., format, structure), whether it's a read-only operation, or any limitations like rate limits or authentication needs. This leaves significant gaps for an AI agent to understand how to handle the tool's behavior.

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 a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It's appropriately sized and front-loaded, making it easy to parse quickly, which is ideal for conciseness.

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

Completeness2/5

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

Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., code snippets, documentation), how examples are structured, or any behavioral traits. For a tool with no structured data beyond the input schema, the description should provide more context to help an AI agent use it effectively.

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?

The input schema has 100% description coverage, with the 'task' parameter clearly documented. The description doesn't add any additional meaning beyond what the schema provides, such as explaining the semantics of example tasks or providing usage context. With high schema coverage, the baseline score of 3 is appropriate, as the schema does the heavy lifting.

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?

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('examples of how to use Opik Comet's API'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'get-opik-help' or 'get-opik-tracing-info', which might provide related but different information.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when it's appropriate (e.g., for learning API usage) or when not to use it (e.g., for direct API calls), nor does it reference sibling tools like 'get-opik-help' that might serve similar purposes.

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

get-opik-helpB

Get contextual help about Opik Comet's capabilities

ParametersJSON Schema

Name	Required	Description	Default
`subtopic`	No	Optional subtopic for more specific help
`topic`	Yes	The topic to get help about (prompts, projects, traces, metrics, or general)

TDQS

B3.1/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves help information, implying a read-only operation, but doesn't mention any behavioral traits like rate limits, authentication needs, or what the output format might be. This is a significant gap for a tool with no annotation coverage.

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 a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It is appropriately sized and front-loaded, making it easy for an agent to parse quickly.

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

Completeness3/5

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

Given the tool's low complexity (2 parameters, no output schema, no annotations), the description is minimally adequate but incomplete. It explains what the tool does but lacks details on behavioral aspects and usage context, which are important for an agent to operate effectively without annotations.

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?

The input schema has 100% description coverage, clearly documenting both parameters ('topic' and 'subtopic') with their types and purposes. The description adds no additional meaning beyond what the schema provides, so it meets the baseline of 3 where the schema does the heavy lifting.

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?

The description clearly states the verb 'Get' and the resource 'contextual help about Opik Comet's capabilities', making the purpose understandable. However, it doesn't specifically differentiate from sibling tools like 'get-opik-examples' or 'get-opik-tracing-info', which also provide information about Opik Comet but focus on different aspects.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives such as 'get-opik-examples' or 'get-opik-tracing-info'. It lacks explicit context, exclusions, or prerequisites, leaving the agent to infer usage based on the tool name alone.

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

get-opik-tracing-infoC

Get information about Opik's tracing capabilities and how to use them

ParametersJSON Schema

Name	Required	Description	Default
`topic`	No	Optional specific tracing topic to get information about (e.g., 'spans', 'distributed', 'multimodal', 'annotations')

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations provided, the description carries full burden but only states what the tool does without disclosing behavioral traits. It doesn't cover aspects like whether it's a read-only operation, potential rate limits, authentication needs, or output format, which are critical for an agent to use it effectively.

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 description is a single, clear sentence that efficiently conveys the tool's purpose without unnecessary words. It's front-loaded and appropriately sized, though it could be slightly more structured by including brief usage hints.

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

Completeness3/5

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

Given the tool's low complexity (one optional parameter, no output schema, no annotations), the description is minimally complete but lacks depth. It explains what the tool does but doesn't provide enough context about behavior or usage relative to siblings, making it adequate but with clear gaps for an agent.

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?

The input schema has 100% description coverage, clearly documenting the optional 'topic' parameter with examples. The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline of 3 for adequate but not enhanced coverage.

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?

The description clearly states the verb 'Get' and the resource 'information about Opik's tracing capabilities and how to use them', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get-trace-by-id' or 'get-trace-stats', which also deal with tracing information but focus on specific data rather than general capabilities.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios like needing overviews versus detailed data, or how it differs from siblings such as 'get-opik-help' or 'get-opik-examples', leaving the agent to infer usage from context alone.

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

get-project-by-idC

Get a single project by ID

ParametersJSON Schema

Name	Required	Description	Default
`projectId`	Yes	ID of the project to fetch
`workspaceName`	No	Workspace name to use instead of the default

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure. While 'Get' implies a read operation, it doesn't specify whether this requires authentication, what happens if the project doesn't exist, or any rate limits. The description lacks crucial behavioral context that would help an agent understand how to handle errors or what to expect from the operation.

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 extremely concise at just 6 words, front-loading the essential information with zero wasted words. Every word earns its place by communicating the core functionality without unnecessary elaboration.

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

Completeness2/5

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

For a read operation with 2 parameters and no output schema, the description is insufficiently complete. It doesn't explain what information the tool returns about projects, how to handle the optional workspaceName parameter, or what format the response takes. With no annotations and no output schema, the agent lacks crucial information about the tool's behavior and outputs.

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 fully documents both parameters (projectId and workspaceName). The description adds no additional parameter information beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description.

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?

The description clearly states the action ('Get') and resource ('a single project by ID'), making the purpose immediately understandable. It distinguishes from sibling tools like 'list-projects' by specifying retrieval of a single item rather than a collection. However, it doesn't explicitly differentiate from 'get-prompt-by-id' or 'get-trace-by-id' which follow similar patterns.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to prefer this over 'list-projects' for single-item retrieval, or how it relates to other 'get-by-id' tools for different resource types. There's also no information about prerequisites or contextual constraints.

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

get-prompt-by-idC

Get a single prompt by ID

ParametersJSON Schema

Name	Required	Description	Default
`promptId`	Yes	ID of the prompt to fetch

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description carries full burden but only states the basic action without disclosing behavioral traits. It doesn't mention if this is a read-only operation, what happens with invalid IDs (e.g., errors), authentication needs, rate limits, or return format, leaving significant gaps in transparency.

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 extremely concise with a single sentence that directly states the tool's purpose, making it front-loaded and free of unnecessary words. Every part of the sentence earns its place by clearly conveying the core functionality.

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

Completeness2/5

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

Given the complexity of a retrieval tool with no annotations and no output schema, the description is incomplete. It doesn't explain what data is returned (e.g., prompt content, metadata), error handling, or how it fits into the broader context of prompt management, failing to compensate for the lack of structured data.

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?

The description adds no meaning beyond the input schema, which has 100% coverage and fully documents the 'promptId' parameter. With high schema coverage, the baseline is 3, as the schema handles parameter documentation adequately without extra detail from the description.

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?

The description clearly states the verb 'Get' and the resource 'a single prompt by ID', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get-project-by-id' or 'list-prompts', which would require mentioning it retrieves individual prompt details rather than projects or lists.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives such as 'list-prompts' for browsing or 'get-project-by-id' for related resources. It lacks context about prerequisites like needing a valid prompt ID or exclusions for non-existent IDs, leaving usage unclear.

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

get-server-infoB

Get information about the Opik server configuration

ParametersJSON Schema

Name	Required	Description	Default
`random_string`	No	Dummy parameter for no-parameter tools

TDQS

B3.1/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden. It states it 'gets' information, implying a read-only operation, but doesn't disclose behavioral traits such as authentication needs, rate limits, response format, or potential side effects. This leaves significant gaps for a tool with no annotation coverage.

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 a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, making it easy to parse quickly.

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

Completeness2/5

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

Given no annotations and no output schema, the description is incomplete. It lacks details on what specific server configuration information is returned, how it's structured, or any behavioral context. For a tool in a set with many siblings, more completeness is needed to guide effective use.

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

Parameters4/5

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

The input schema has 1 parameter with 100% coverage, describing it as a 'Dummy parameter for no-parameter tools'. The description adds no parameter information, which is acceptable since the schema fully documents the parameter, and the tool effectively has 0 functional parameters. Baseline is 3, but the dummy nature justifies a higher score for clarity.

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?

The description clearly states the verb 'Get' and resource 'information about the Opik server configuration', making the purpose specific and understandable. However, it doesn't differentiate from sibling tools like 'get-metrics' or 'get-opik-tracing-info', which also retrieve server-related information, so it misses full sibling distinction.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. With siblings like 'get-metrics' and 'get-opik-tracing-info' that might retrieve overlapping or related server data, there's no indication of context, prerequisites, or exclusions for tool selection.

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

get-trace-by-idC

Get a single trace by ID

ParametersJSON Schema

Name	Required	Description	Default
`traceId`	Yes	ID of the trace to fetch
`workspaceName`	No	Workspace name to use instead of the default

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it's a read operation ('get'), but doesn't cover aspects like error handling (e.g., what happens if the trace ID doesn't exist), rate limits, authentication requirements, or response format. For a tool with no annotation coverage, this leaves significant gaps in understanding its behavior.

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 a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose ('Get a single trace by ID'), making it immediately understandable. Every part of the sentence contributes directly to clarifying the tool's function.

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

Completeness2/5

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

Given no annotations and no output schema, the description is incomplete for a tool with 2 parameters. It lacks details on behavioral traits (e.g., error cases, permissions), return values, and usage context. While the schema covers parameters well, the overall context for safe and effective use is insufficient, especially for a read operation that might involve workspace-specific data.

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%, with clear descriptions for both parameters: 'traceId' as the ID to fetch and 'workspaceName' as an optional override. The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate.

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?

The description 'Get a single trace by ID' clearly states the action (get) and resource (trace), with specificity about retrieving by ID. It distinguishes from siblings like 'list-traces' (multiple) and 'get-trace-stats' (statistics), though it doesn't explicitly name them. The purpose is unambiguous but lacks explicit sibling differentiation.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose it over 'list-traces' for multiple traces or 'get-trace-stats' for aggregated data, nor does it specify prerequisites like authentication or workspace context. Usage is implied by the name but not explicitly stated.

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

get-trace-statsC

Get statistics for traces

ParametersJSON Schema

Name	Required	Description
`endDate`	No	End date in ISO format (YYYY-MM-DD)
`projectId`	No	Project ID to filter traces
`projectName`	No	Project name to filter traces
`startDate`	No	Start date in ISO format (YYYY-MM-DD)
`workspaceName`	No	Workspace name to use instead of the default

TDQS

C2.7/5.0

Behavior2/5

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

With no annotations provided, the description carries full burden but only states it 'gets' statistics without disclosing behavioral traits like read-only nature, potential rate limits, authentication needs, or what happens if parameters are omitted. It fails to compensate for the lack of annotations.

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 a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, making it easy to parse quickly without unnecessary elaboration.

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

Completeness2/5

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

Given the tool's complexity (5 parameters, no output schema, no annotations), the description is incomplete. It doesn't explain what statistics are returned, how they're formatted, or error conditions, leaving significant gaps for the agent to infer behavior.

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 parameters are fully documented in the schema. The description adds no meaning beyond the schema, such as explaining how parameters interact or default behaviors. Baseline 3 is appropriate as the schema does the heavy lifting.

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

Purpose3/5

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

The description 'Get statistics for traces' states a clear verb ('Get') and resource ('statistics for traces'), but it's vague about what specific statistics are retrieved and doesn't distinguish from sibling tools like 'get-metrics' or 'get-trace-by-id'. It provides basic purpose but lacks specificity.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like 'get-metrics' or 'list-traces'. The description doesn't mention prerequisites, exclusions, or context for usage, leaving the agent without direction on tool selection.

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

list-projectsC

Get a list of projects/workspaces

ParametersJSON Schema

Name	Required	Description
`page`	Yes	Page number for pagination
`size`	Yes	Number of items per page
`sortBy`	No	Sort projects by this field
`sortOrder`	No	Sort order (asc or desc)
`workspaceName`	No	Workspace name to use instead of the default

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure. It states it 'gets a list' which implies a read operation, but doesn't mention pagination behavior (implied by parameters), rate limits, authentication requirements, or what the return format looks like. For a tool with 5 parameters and no output schema, this leaves significant behavioral aspects undocumented.

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 extremely concise at just 5 words, front-loading the core purpose with zero wasted words. Every element ('Get', 'list', 'projects/workspaces') earns its place. No structural issues or unnecessary elaboration.

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

Completeness2/5

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

For a tool with 5 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what a 'project' or 'workspace' represents in this context, doesn't describe the return format, and provides no behavioral context. The agent would need to infer too much from just the schema parameters.

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 all parameters are documented in the schema. The description adds no additional parameter information beyond what's already in the schema descriptions. It doesn't explain relationships between parameters (e.g., how 'workspaceName' interacts with the list) or provide usage examples. Baseline 3 is appropriate when schema does the heavy lifting.

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?

The description clearly states the action ('Get a list') and resource ('projects/workspaces'), making the purpose immediately understandable. However, it doesn't distinguish between 'projects' and 'workspaces' or clarify if they're synonymous, and it doesn't differentiate from sibling tools like 'get-project-by-id' or 'list-prompts' which serve different but related purposes.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose 'list-projects' over 'get-project-by-id' for retrieving specific projects, or 'list-prompts' for different resource types. There are no prerequisites, exclusions, or context for usage decisions.

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

list-promptsC

Get a list of Opik prompts

ParametersJSON Schema

Name	Required	Description	Default
`page`	Yes	Page number for pagination
`size`	Yes	Number of items per page

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool retrieves a list but doesn't mention pagination behavior (implied by parameters), rate limits, authentication needs, or what the return format looks like (no output schema). This leaves significant gaps for an agent to understand how the tool behaves.

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 a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose and appropriately sized for a simple list operation, making it easy for an agent to parse quickly.

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

Completeness2/5

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

For a list tool with 2 required parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain pagination requirements, return format, or error conditions. Given the complexity (simple but with required params) and lack of structured data, more context is needed for the agent to use this tool effectively.

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%, with both parameters ('page' and 'size') clearly documented in the schema. The description adds no additional parameter semantics beyond implying list retrieval, so it meets the baseline score of 3 where the schema does the heavy lifting.

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?

The description 'Get a list of Opik prompts' clearly states the verb ('Get') and resource ('Opik prompts'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'list-projects' or 'list-traces' beyond the resource type, nor does it specify scope (e.g., all prompts vs. filtered).

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives like 'get-prompt-by-id' for retrieving a specific prompt, or 'create-prompt' for adding new prompts. There's no mention of prerequisites, typical use cases, or limitations that would help an agent choose appropriately.

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

list-tracesC

Get a list of traces

ParametersJSON Schema

Name	Required	Description
`page`	Yes	Page number for pagination
`projectId`	No	Project ID to filter traces
`projectName`	No	Project name to filter traces
`size`	Yes	Number of items per page
`workspaceName`	No	Workspace name to use instead of the default

TDQS

C2.7/5.0

Behavior2/5

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

With no annotations, the description carries full burden but only states the action without disclosing behavioral traits. It doesn't mention if this is a read-only operation, pagination behavior, rate limits, authentication needs, or what the output looks like (e.g., list format, error handling). This leaves significant gaps for a tool with 5 parameters.

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 a single, clear sentence with no wasted words. It's front-loaded and efficiently conveys the core action, making it easy to parse quickly without unnecessary detail.

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

Completeness2/5

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

Given the tool's complexity (5 parameters, no output schema, no annotations), the description is incomplete. It doesn't explain the return values, pagination implications, or how filtering parameters interact, leaving the agent with insufficient context to use the tool effectively beyond basic invocation.

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 parameters like 'page', 'size', 'projectId' are well-documented in the schema. The description adds no additional meaning beyond 'list of traces', such as explaining how filtering works or parameter interactions, meeting the baseline for high schema coverage.

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

Purpose3/5

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

The description 'Get a list of traces' states the basic action (get/list) and resource (traces), making the purpose understandable. However, it's vague about what 'traces' are (e.g., execution traces, logging traces) and doesn't distinguish from siblings like 'get-trace-by-id' or 'get-trace-stats', missing specificity for a 4-5 score.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like 'get-trace-by-id' for single traces or 'get-trace-stats' for aggregated data. The description lacks context about filtering capabilities or typical use cases, offering minimal help for selection.

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

update-projectC

Update a project

ParametersJSON Schema

Name	Required	Description
`description`	No	New project description
`name`	No	New project name
`projectId`	Yes	ID of the project to update
`workspaceName`	No	Workspace name to use instead of the default

TDQS

C2.7/5.0

Behavior2/5

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

No annotations are provided, so the description carries full burden. 'Update a project' implies a mutation operation but doesn't disclose behavioral traits like required permissions, whether changes are reversible, rate limits, or what happens to unspecified fields. It lacks critical context for a write operation.

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 extremely concise with a single sentence, 'Update a project', which is front-loaded and wastes no words. It efficiently communicates the core action, though this brevity contributes to gaps in other dimensions.

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

Completeness2/5

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

Given the tool's complexity as a mutation with 4 parameters and no annotations or output schema, the description is incomplete. It doesn't cover behavioral aspects, usage context, or return values, leaving significant gaps for an AI agent to understand and invoke it correctly.

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 all parameters (projectId, name, description, workspaceName). The description adds no meaning beyond what the schema provides, such as explaining interdependencies or default behaviors. Baseline 3 is appropriate when schema does the heavy lifting.

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

Purpose3/5

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

The description 'Update a project' states the verb and resource but is vague about what aspects can be updated. It distinguishes from siblings like 'create-project' and 'delete-project' by specifying 'update', but doesn't clarify scope compared to 'update-prompt' or differentiate from partial updates vs full replacements.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives is provided. The description doesn't mention prerequisites (e.g., needing an existing project), exclusions, or comparisons to siblings like 'get-project-by-id' for read operations or 'list-projects' for discovery.

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

update-promptC

Update a prompt

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes	New name for the prompt
`promptId`	Yes	ID of the prompt to update

TDQS

C2.1/5.0

Behavior1/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure but offers none. It doesn't indicate whether this is a read-only or destructive operation, what permissions are required, whether changes are reversible, what happens on success/failure, or any rate limits. For a mutation tool with zero annotation coverage, this complete lack of behavioral information is inadequate and potentially misleading.

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 maximally concise at just three words, with zero wasted language. Every word earns its place by identifying the core action and resource. While this conciseness comes at the expense of completeness, the structure is front-loaded and efficient from a pure brevity perspective.

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

Completeness2/5

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

Given that this is a mutation tool with no annotations and no output schema, the description is severely incomplete. It doesn't explain what 'updating' entails beyond the name parameter, what happens to other prompt attributes, what the tool returns, or any error conditions. For a tool that modifies data, this minimal description leaves critical gaps in understanding its behavior and outcomes.

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?

The schema description coverage is 100%, with both parameters ('promptId' and 'name') clearly documented in the schema. The description adds no additional parameter information beyond what the schema already provides. According to scoring rules, when schema coverage is high (>80%), the baseline score is 3 even with no parameter information in the description, which applies here.

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

Purpose2/5

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

The description 'Update a prompt' is a tautology that restates the tool name without adding meaningful context. While it correctly identifies the verb ('update') and resource ('prompt'), it fails to specify what aspects of a prompt can be updated or distinguish this tool from sibling tools like 'update-project'. This minimal statement provides no differentiation or specificity beyond the name itself.

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

Usage Guidelines1/5

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

The description provides absolutely no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing prompt ID), exclusions, or relationships to sibling tools like 'create-prompt', 'delete-prompt', or 'get-prompt-by-id'. Without any context about appropriate usage scenarios, the agent has no basis for making informed decisions about tool selection.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

19 tool updatesv1.0.0Aug 18, 2025
- First observedcreate-project
- First observedcreate-prompt
- First observedcreate-prompt-version
- First observeddelete-project
- First observeddelete-prompt
- First observedget-metrics
- First observedget-opik-examples
- First observedget-opik-help
- First observedget-opik-tracing-info
- First observedget-project-by-id
- First observedget-prompt-by-id
- First observedget-server-info
- First observedget-trace-by-id
- First observedget-trace-stats
- First observedlist-projects
- First observedlist-prompts
- First observedlist-traces
- First observedupdate-project
- First observedupdate-prompt

Deploy Server

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

TDQS

B3.1/5.0

Scored 2026-04-18 11:20 across 19 tools

Disambiguation5/5

Each tool has a clearly distinct purpose targeting specific resources (projects, prompts, traces, metrics, help) and actions (create, get, list, update, delete). There is no overlap or ambiguity between tools, making it easy for an agent to select the right one for any operation.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with hyphens (e.g., create-project, get-project-by-id, list-projects). The naming is uniform across all 19 tools, using clear verbs like create, get, list, update, and delete paired with specific nouns.

Tool Count4/5

With 19 tools, the count is slightly high but reasonable for a comprehensive server covering projects, prompts, traces, metrics, and help. It feels well-scoped for the Opik domain, though it borders on being heavy compared to typical 3-15 tool ranges.

Completeness5/5

The tool set provides complete CRUD/lifecycle coverage for projects and prompts (create, get, list, update, delete), with additional tools for traces, metrics, and help. There are no obvious gaps; agents can perform all core operations without dead ends in this domain.

Maintenance

ActivityActive

ResponsivenessUnresponsive

Resources

Need Help?

Reddit Discussion

Related Servers

Related MCP Connectors

mcp COAuth
com.wix
A Model Context Protocol server for Wix AI tools
Developer Tools Content Management Systems App Automation
216
Studex MCP ServerOAuth
io.github.itshivams
Model Context Protocol server for Studex tools, notifications, and profile integrations
Developer Tools
1
hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
238
Apideck MCP A
dev.apideck.mcp
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Developer Tools
42

Related MCP Servers

MCP Server
RAG Systems Databases File Systems
GobinFan
F
license
B
quality
D
maintenance
Implements the Model Context Protocol (MCP) to provide AI models with a standardized interface for connecting to external data sources and tools like file systems, databases, or APIs.
Updated a year ago (2025-05-05 08:18 UTC)
1
153
-
dap-mcp
Developer Tools Code Execution
KashunCheng
A
license
Not graded
quality
C
maintenance
An implementation of the Model Context Protocol (MCP) that enables interaction with debug adapters, allowing language models to control debuggers, set breakpoints, evaluate expressions, and navigate source code during debugging sessions.
Updated a year ago (2025-09-24 00:19 UTC)
40
AGPL 3.0
MCP Python Server
Code Execution
jatindera
F
license
Not graded
quality
D
maintenance
A Python-based implementation of the Model Context Protocol that enables communication between a model context management server and client through a request-response architecture.
Updated a year ago (2025-03-28 03:07 UTC)
-
Python MCP Server Template
HappyPathway
-
license
Not graded
quality
D
maintenance
A standardized foundation for building Model Context Protocol servers that integrate with VS Code, using Python with stdio transport for seamless AI tool integration.
Updated a year ago (2025-04-25 18:42 UTC)
-

Appeared in Searches

Exploring the Concept of Multi-Agentic Systems