MCP tools

This page lists every tool the Hue MCP server serves, grouped by the toolsets you name in ?toolsets=, with the access each one needs. Hue MCP describes what the tools do together, and Recipes gives tool sequences for common questions. The connection itself is the authority on the exact arguments: search_hue_tools returns each tool’s input schema as your connection publishes it.

Choose toolsets

This section describes connections without Code Mode. Without a selection, a connection lists the observe toolset, the production reads: list_projects, get_project_context, search_traces, get_trace, get_span, list_sessions, verify_trace, get_span_content, search_spans, aggregate, get_intent_summary, list_intent_traces, get_request_answer, search_hue_docs and load_hue_guide. Beside them it lists three catalog tools that reach every other tool the connection’s access allows, so a short list loses nothing:

search_hue_tools finds tools by keyword or toolset, 10 per page. Results include name, toolset, summary, access, input_schema, annotations and call.
execute_hue_tool calls a read tool by name with its arguments and returns exactly what calling it directly returns.
execute_hue_write_tool calls a write tool the same way. It is listed only with write access and without ?read_only=true.

That is 18 tools with write access, or 17 tools with Read access. An executor call goes through the same access checks, project selection, audit log and content gating as a direct call. For example, to list an organization project’s eval sets on a default connection, call list_projects, then search_hue_tools with query: "eval set", then execute_hue_tool with {"name": "list_eval_sets", "arguments": {"project_id": "<id>"}}. To list tools directly, add ?toolsets=<names> to the server URL or send the X-Hue-MCP-Toolsets: <names> header; both selections form their union. Separate names with commas. author, evaluate, import and outreach match the MCP guides of the same names, debug lists the tools for building a World from one trace, and the other names are the toolset groups below:

Selection	Directly listed tools
`observe`	The 15 production reads listed above.
`author`	`search_traces`, `get_trace`, `list_eval_sets`, `get_eval_set`, `add_eval_set`, `update_eval_set`, `add_eval_set_draft`, `add_eval_set_cases`, `update_eval_set_case`, `rename_eval_set_case`, `delete_eval_set_case`, `freeze_eval_set_version`, `list_evaluators`, `get_evaluator`, `add_evaluator`, `publish_evaluator`, `copy_evaluator`, `update_evaluator`, `set_evaluator_check_descriptions`, `set_tags`, `list_runs`, `get_run`, `add_run`, `update_run`, `list_run_items`, `get_run_item`, `start_run_case`, `complete_run_case`, `finish_run`, `list_agents`, `preflight_run`, `launch_run`, `get_local_run`, `recover_local_run`, `get_managed_run`, `get_case_conversion_eligibility`, `add_case_conversion`, `get_case_conversion`, `update_case_conversion`, `publish_case_conversion`, `archive_case_conversion`, `list_worlds`, `create_world`, `create_world_variation`, `get_world_creation`, `cancel_world_creation`, `get_world_definition`, `update_world`, `publish_world_version`, `get_world_overview`, `get_world_edit_context`, `edit_world`, `list_instances`, `start_instance`.
`evaluate`	`load_hue_guide`, `get_trace`, `get_span`, `list_cases`, `get_case`, `get_eval_set`, `freeze_eval_set_version`, `get_case_conversion_eligibility`, `add_case_conversion`, `get_case_conversion`, `update_case_conversion`, `publish_case_conversion`, `get_world_definition`, `list_agents`, `refresh_agents`, `preflight_run`, `launch_run`, `get_local_run`, `recover_local_run`, `get_managed_run`, `get_run`, `list_run_items`, `get_run_item`, `get_run_execution`, `get_case_divergence`.
`import`	`list_projects`, `get_project_context`, `load_hue_guide`, `prepare_trace_import`, `get_trace_import`, `search_traces`, `get_trace`, `verify_trace`.
`debug`	`get_world_overview`, `get_world_edit_context`, `edit_world`, `load_hue_guide`, `list_worlds`, `get_world_definition`, `prepare_trace_upload`, `complete_trace_upload`, `create_world_from_trace`, `update_world`, `get_world_build`, `retry_world_build`, `prepare_world_import`, `publish_world_import`, `get_world_import`, `list_world_models`, `get_world_model`, `get_world_apps`, `list_apps`, `get_app`, `list_instances`, `start_instance`, `reproduce_instance`, `restart_instance`, `finish_instance`, `get_instance_connections`, `get_instance`, `get_instance_state`, `list_instance_steps`, `list_instance_requests`, `get_instance_diff`, `send_instance_input`.
`outreach`	`load_hue_guide`, `list_worlds`, `get_world_definition`, `list_instances`, `start_instance`, `get_instance`, `get_instance_connections`, `list_world_people`, `act_as_person`, `create_notification`, `set_person_responses`, `patch_world_record`, `list_scheduled_events`, `cancel_scheduled_event`, `get_world_clock`, `set_world_settings`, `set_world_step`, `advance_world_clock`, `finish_instance`, `get_instance_diff`, `list_instance_steps`, `save_instance_case`, `check_instance_case`.
`project`	`list_projects`, `add_project`, `get_project_context`, `assess_pending_traces`, `submit_product_feedback`, `list_api_keys`, `add_api_key`, `revoke_api_key`, `list_members`, `update_project`.
`traces`	`search_traces`, `get_trace`, `get_span`, `list_sessions`, `verify_trace`, `delete_traces`, `get_trace_deletion`, `get_span_content`, `search_spans`, `aggregate`, `list_trace_checks`, `get_trace_checks`, `save_trace_checks`, `set_trace_checks_consent`, `test_trace_checks`, `activate_trace_checks`, `deactivate_trace_checks`, `reassess_trace_checks`, `get_trace_check_results`, `get_trace_check_summary`, `prepare_trace_import`, `get_trace_import`.
`eval_sets`	`list_eval_sets`, `get_eval_set`, `list_evaluators`, `get_evaluator`, `add_eval_set`, `update_eval_set`, `add_eval_set_draft`, `add_eval_set_cases`, `update_eval_set_case`, `rename_eval_set_case`, `delete_eval_set_case`, `freeze_eval_set_version`, `add_evaluator`, `publish_evaluator`, `copy_evaluator`, `set_evaluator_check_descriptions`, `set_tags`, `archive_eval_set`, `update_evaluator`, `archive_evaluator`.
`runs`	`list_runs`, `get_run`, `add_run`, `list_run_items`, `get_run_item`, `get_run_execution`, `start_run_case`, `complete_run_case`, `finish_run`, `list_scoring_runs`, `get_scoring_run`, `add_scoring_run`, `add_scoring_results`, `update_run`.
`judges`	`list_judge_results`, `get_judge_alignment`, `label_judge_result`, `set_judge_promotion`, `check_judge_regression`, `set_judge_alignment_bar`, `get_judge_budget`, `add_judge_jobs`, `cancel_judge_jobs`.
`cases`	`list_cases`, `get_case`, `get_case_conversion_eligibility`, `add_case_conversion`, `get_case_conversion`, `update_case_conversion`, `publish_case_conversion`, `archive_case_conversion`, `get_case_divergence`, `list_suggested_cases`, `add_case_conversion_batch`, `get_case_conversion_batch`, `update_case_conversion_batch`.
`runners`	`list_agents`, `refresh_agents`, `preflight_run`, `launch_run`, `add_managed_target`, `get_managed_run`, `cancel_managed_run`, `get_local_run`, `recover_local_run`, `list_artifacts`, `get_artifact`.
`worlds`	`list_worlds`, `get_world_definition`, `update_world`, `publish_world_version`, `archive_world`, `get_world_overview`, `get_world_edit_context`, `edit_world`, `prepare_trace_upload`, `complete_trace_upload`, `create_world_from_trace`, `get_world_build`, `retry_world_build`, `prepare_world_import`, `publish_world_import`, `get_world_import`, `generate_world`, `get_world_generation`, `cancel_world_creation`, `create_world_variation`, `create_world`, `get_world_creation`, `list_world_models`, `get_world_model`, `get_world_apps`, `list_apps`, `get_app`.
`instances`	`list_instances`, `start_instance`, `reproduce_instance`, `restart_instance`, `finish_instance`, `get_instance_connections`, `get_instance`, `get_instance_state`, `get_instance_diff`, `list_instance_steps`, `list_instance_requests`, `send_instance_input`, `act_as_person`, `create_notification`, `set_person_responses`, `list_scheduled_events`, `cancel_scheduled_event`, `list_world_people`, `get_world_clock`, `set_world_settings`, `set_world_step`, `advance_world_clock`, `patch_world_record`, `save_instance_case`, `check_instance_case`.
`intents`	`get_intent_taxonomy`, `save_intent_taxonomy`, `classify_pending_intents`, `get_intent_summary`, `list_intent_traces`, `get_request_answer`.
`docs`	`search_hue_docs`, `load_hue_guide`.
`all`	Every tool your access allows, without the catalog tools. Use it for clients that search their own tool lists and load a definition only when a task needs it.

The earlier environments selection lists worlds and instances. A call to a tool’s earlier name, such as list_environments, start_environment_world, list_local_agents or launch_local_run, answers not_found naming the tool that replaced it and its renamed arguments, and executes nothing. The retired add_world and add_environment tools also answer not_found, point to create_world, and execute nothing. Their old arguments are incompatible with create_world. MCP no longer supports creating a World identity without publishing a version, choosing a custom slug, or creating an identity first to publish an authored definition with custom actions.

Client	Server URL	Why
Claude Code, Codex, Conductor	`https://mcp.hue.run/mcp?toolsets=all`	They search their own tool lists, so every tool costs little.
Claude.ai and Claude Desktop connectors, ChatGPT	`https://mcp.hue.run/mcp` for production reads, or `https://mcp.hue.run/mcp?toolsets=all` for everything	A connector takes only a URL.
Cursor	`https://mcp.hue.run/mcp?toolsets=observe`	Cursor caps the tools it loads across servers; the URL keeps listing the production reads.
VS Code, Windsurf, Gemini CLI and other clients	`https://mcp.hue.run/mcp`	The production reads and the catalog tools.

On ordinary toolset connections, list_projects and get_project_context are always listed, and get_project_context reports the selection as toolsets: the names selected, a source of default when the connection named none, any names it ignored, the names available, and, when some tools are not listed, their count per group as unlisted with a widen hint on how to reach them. An unknown name never fails a request; a selection with only unknown names lists the default. Read access and ?read_only=true still apply inside a selection. A client keeps the tool list it read when it connected: after you change the URL, restart the client, or remove a connector and add it again.

Code Mode

Code Mode requires a valid Read or Read and write API key, or an authenticated sign-in connection. The optional URL https://mcp.hue.run/mcp?code_mode=true replaces the toolset listing. Code Mode lists 4 tools with write access, or 3 tools with Read access. read_only=true also hides the write executor.

Tool	Purpose
`search_hue_tools`	Discovers permitted tools and their input schemas. Add `include_output_schema: true` for output schemas. Each result’s `call` says how to invoke it. Project reads also expose `native_call` and `native_input_schema` for the native executor.
`execute_hue_tool`	Calls any permitted read, including `list_projects`, with its ordinary MCP result. Use it when a read exceeds a program budget.
`execute_hue_write_tool`	Calls writes separately, with the existing permissions and approval hints. Hidden on read-only connections.
`execute_hue_code`	Runs a read-only JavaScript function body that calls project reads with `await hue.call(name, arguments)` and returns a JSON value.

Combine URL parameters with &, for example 'https://mcp.hue.run/mcp?code_mode=true&read_only=true'. Keep shell URLs quoted. code_mode=true takes precedence over the toolset listing, including toolsets=all. Remove it to restore that listing, then reconnect the client. Call execute_hue_tool with {"name": "list_projects", "arguments": {}} first. Pass the chosen project_id once on execute_hue_code; every hue.call in that program omits it. An API key can omit the outer selector to use its default project. Pinned connections must omit it. For a project read through execute_hue_tool, follow native_input_schema and put project_id inside arguments instead. An unpinned organization sign-in connection requires that selector. For example, pass this function body as code to execute_hue_code to compare two production windows:

const [recent, earlier] = await Promise.all([
	hue.call("aggregate", { since: "24h", metrics: ["count", "error_count"] }),
	hue.call("aggregate", { since: "48h", until: "24h", metrics: ["count", "error_count"] })
]);
return { recent, earlier };

hue.call returns the tool’s structured result. The program’s return value appears in structuredContent.value; execution counters appear in structuredContent.usage. Await every call before returning. Use existing aggregate and answer tools for their calculations, and return the evidence the agent needs to interpret the result. Writes, including launching runs and starting World instances, stay outside the program in execute_hue_write_tool. Each read uses the authenticated connection’s permissions, content opt-in, redaction and auditing. Recorded content remains untrusted data. The runtime exposes no imports, direct network access, filesystem or host credentials. An uncaught tool error preserves its Hue error code and retry guidance. Invalid JavaScript or a result that cannot serialize as JSON answers invalid_argument; time limits and cancellation answer timeout.

Limit per program	Value
Source	32 KiB
Hue calls	16
Concurrent Hue calls	4
Wall time	20 seconds
JavaScript CPU time	1 second
JavaScript heap	16 MiB
Data exchanged with Hue tools	1 MiB total
Returned JSON	64 KiB

These are per-program safeguards, not a per-user request quota. Up to four reads run at once within a program; additional reads wait. Up to two programs run at once per service process; additional programs wait in a bounded queue. Queueing counts toward the 20-second wall limit or an earlier request deadline. An overloaded queue returns a retryable error. Limits stop the program with an error. Narrow the work, split it into programs, or use execute_hue_tool with the discovered native_call and native_input_schema. The native executor preserves the ordinary MCP result without the program’s transfer or return-size budgets. Inner tools retain their own pagination, result sizes and time limits. Hue runs each program in an isolated JavaScript runtime within its existing service, without a separate hosted sandbox for each execution. It runs the generated JavaScript, not the client’s whole agent. Execution still consumes CPU and memory, and its reads still use backend resources. Latency and token use depend on the task and client.

Access levels

The Access column of each table uses these levels. A level can add a role requirement after a comma. Organization access also applies to keys and sign-in connections. For a trial organization, Read and write does not unlock tracing or evaluations. The shared key in a trial’s agent prompt cannot use owner- or admin-only tools, including creating or revoking project keys. This restriction also applies when an owner or admin replaces the shared key. Manage the organization in Settings.

Access	Needs	Before calling
Read	A Read or Read and write key, or a sign-in connection	Nothing, though recorded content (`include_content: true`, `get_span_content`) is audited and is untrusted data.
Write	A Read and write key or a sign-in connection, with no `?read_only=true` on the URL or `X-Hue-MCP-Read-Only: true` header	Nothing.
Destructive	The same as Write. The tool changes or removes existing data, or stops work: it updates, sets, activates or deactivates, archives, cancels, revokes or deletes, or freezes, seals, publishes or supersedes something that exists, and carries `destructiveHint: true`	A client that gates approval on `destructiveHint` asks you first. Don’t auto-approve it.
owner or admin	The member who created the key, still a verified member, or the member who signed in must currently be an owner or admin of the organization	Ask an owner or admin when you are not one.
owner or admin through sign-in	A Read and write key can call it; a sign-in connection needs an owner or admin	The same.
key only	A Read and write key whose creator is an owner or admin. A sign-in connection never lists it	Create keys in Settings → API keys instead.
sign-in only	A sign-in connection for the whole organization. Keys and pinned connections never list it	Sign in with Hue without a project pin.

Permissions

To	You need
Read traces, spans, sessions, findings, trace checks, intents, request answers, eval sets, evaluators, runs, cases, Worlds, saved instances, judges, members and keys	Any MCP credential: a Read or Read and write key, or sign-in.
Read recorded content	The same, and the application must have captured it. Each read is recorded in the project’s audit log.
Create and change eval sets, evaluators, runs, cases, Worlds, judge labels and promotions, and launch runs on connected agents	Read and write access: a Read and write key or sign-in, without `?read_only=true`.
Build a World, start, restart or finish an instance, or reveal its connection token	Read and write access: a Read and write key or sign-in, without `?read_only=true`.
Delete traces or inspect deletion progress, revoke keys, change project settings, register managed targets, publish the intent taxonomy, change the judge alignment bar, or queue findings or intent classification for traces that missed them	Read and write access, and an owner or admin: the key’s creator, or the signed-in member.
Create a project	A sign-in connection for the organization, by an owner or admin. Never through a key.
Change trace checks, or archive eval sets and evaluators	Read and write access; through sign-in, an owner or admin.
Create a project key	A Read and write key created by an owner or admin. Never through sign-in.
Change billing or the plan, invite members or change roles	Settings in Hue. No MCP tool does this.

Tools by toolset

`project`

On ordinary toolset connections, list_projects and get_project_context are listed under every selection.

Tool	Access	What it does
`list_projects`	Read	Lists the active projects the connection reaches, with ids, slugs and links, and reports the connection’s credential, access and toolsets.
`add_project`	Write, owner or admin, sign-in only	Creates a project in the approved organization and returns its id and slug to pass as `project_id`; the same `idempotency_key` and body return the project it created.
`get_project_context`	Read	Reports the selected project, the credential’s access (`can_write`, `read_only`, `can_manage` for sign-in), limits, content policy, listed toolsets and which `features` are set up.
`assess_pending_traces`	Write, owner or admin	Queues the findings pass for a range’s traces that still lack findings, as the Findings settings’ recovery action does.
`list_api_keys`	Read	Lists the organization’s keys with name, preset and dates. Never returns a secret.
`add_api_key`	Write, key only	Creates an organization-wide API key and returns its token once.
`revoke_api_key`	Destructive, owner or admin	Revokes an API key in the organization. A key cannot revoke itself, and revoking a revoked key changes nothing.
`list_members`	Read	Lists the organization members who can open the project, with their roles.
`update_project`	Destructive, owner or admin	Changes the project’s name and description. It still accepts the former AI-processing fields `trace_findings`, `ai_trace_findings`, `ai_intent_classification`, `ai_request_classifiers` and `ai_case_conversion_suggestions`, but ignores them; its result and `get_project_context` report each as `true`.
`submit_product_feedback`	Write	Sends user-requested product feedback with a stable idempotency key and returns a receipt.

`traces`

Listed by default: search_traces, get_trace, get_span, list_sessions, verify_trace, get_span_content, search_spans and aggregate. The trace-check tools produce results only for projects set up for trace checks, and the import tools serve Bulk import existing traces. search_traces, search_spans, aggregate and list_sessions leave out traces your runs recorded unless run_traces is include, only or a run id; see traces from runs.

Tool	Access	What it does
`search_traces`	Read	Finds traces in a window by status, attention, finding, trace check, user, release, trace name, model, root attribute, deployment environment, run, session, duration or text, newest or longest first.
`get_trace`	Read	Returns one trace with its stored findings and trace-check results and a page of its span tree; recorded content with `include_content: true`.
`get_span`	Read	Returns one span’s status and error message, timing, model, usage, tool and attribute names and the files it records; recorded values and file download links with `include_content: true`, and correlated logs with `include_logs: true`.
`list_sessions`	Read	Lists sessions by last activity, with status, trace count and token and span totals.
`verify_trace`	Read	Checks a receipt: whether a trace and its expected spans are stored and which fields are present, never content.
`get_span_content`	Read	Reads exact recorded values from up to 20 spans of one trace, or from up to 20 correlated logs of one span with `log_ids`, by JSON path or attribute key, in slices.
`search_spans`	Read	Finds spans across traces in a window of up to 7 days, by name, kind, status, model, duration, attribute or their trace’s fields.
`aggregate`	Read	Counts, error counts, percentiles and token sums over a window’s traces or spans, grouped by up to two dimensions.
`list_trace_checks`	Read	Reports the active trace-check version and which checks are enabled.
`get_trace_checks`	Read	Returns one trace-check version’s criteria, examples, thresholds and calibration, with the revision writes need.
`save_trace_checks`	Write, owner or admin through sign-in	Saves a new draft version of the four checks without activating it.
`set_trace_checks_consent`	Destructive, owner or admin	Deprecated: trace checks need no consent. Changes nothing and returns the configuration with `consent: true`.
`test_trace_checks`	Write, owner or admin through sign-in	Queues a test of a saved version on up to ten recorded traces, without activating it.
`activate_trace_checks`	Destructive, owner or admin through sign-in	Activates a version whose enabled checks reach 90% precision and 80% recall on held-out labels.
`deactivate_trace_checks`	Destructive, owner or admin through sign-in	Stops automatic checks, keeping versions, calibration and past results.
`reassess_trace_checks`	Write, owner or admin through sign-in	Queues up to 100 traces from a window of up to 7 days for the active version.
`get_trace_check_results`	Read	Pages trace-check results with their criteria and source links; bounded excerpts with `include_content: true`.
`get_trace_check_summary`	Read	Summarizes trace-check coverage and request timing over a window, by intent and request start source.
`prepare_trace_import`	Write	Authorizes delivery of the bundle `hue traces import prepare` wrote into the project and returns the import id, the upload URL and a one-day authorization the helper presents instead of a project key; the same manifest digest renews an interrupted import.
`get_trace_import`	Read	Reports an import’s progress: traces declared, verified, held, excluded and conflicted, traces without a history owner or of unknown origin, batches and values pending, World capture of the verified traces with counts by reason (`by_reason`), and the pending or conflicting traces with their pending batches, capture state and reason, and links.
`delete_traces`	Destructive, owner or admin	Queues permanent trace deletion and downstream cleanup. Selectors combine with OR; environment and time constraints apply to every match. Includes all history and run traces unless constrained. Poll `get_trace_deletion` for completion and failures.
`get_trace_deletion`	Write, owner or admin	Reports a trace deletion or preview’s phases, counts, failures and retry progress. Completion proves active-store cleanup; backup expiry is reported separately when verified.

`eval_sets`

Eval sets and evaluators.

Tool	Access	What it does
`list_eval_sets`	Read	Lists eval sets with names, descriptions, tags and links; `tags` keeps those carrying any of the named tags.
`get_eval_set`	Read	Returns an eval set’s versions, one page of cases (values with `include_content: true`) and a run block with the `hue eval --set` command.
`list_evaluators`	Read	Lists evaluators with ownership, tags and links; `tags` filters them the same way.
`get_evaluator`	Read	Returns an evaluator’s published versions with kind, digest and definition.
`add_eval_set`	Write	Creates an eval set with an empty draft version.
`update_eval_set`	Destructive	Renames an eval set or changes its slug or description.
`add_eval_set_draft`	Write	Opens the eval set’s one draft version, optionally cloned from a frozen version.
`add_eval_set_cases`	Write	Appends 1 to 25 cases to a draft version.
`update_eval_set_case`	Destructive	Replaces a draft case, which clears its link to a source trace.
`rename_eval_set_case`	Destructive	Changes a case’s display title or description on a draft or a saved version; the case key, inputs, expected values and a saved version’s content digest never change.
`delete_eval_set_case`	Destructive	Removes one case from a draft version.
`freeze_eval_set_version`	Destructive	Freezes a draft version so its cases never change and runs can pin it.
`add_evaluator`	Write	Creates a code-owned evaluator, which any key or sign-in connection can publish versions of.
`publish_evaluator`	Write	Publishes an immutable version of a code-owned evaluator, such as one using the built-in `hue.exact_match.v1`.
`copy_evaluator`	Write	Copies an evaluator version, such as one made in Hue, into a new code-owned evaluator.
`set_evaluator_check_descriptions`	Destructive	Sets or clears the descriptions of an evaluator’s checks, which every version, its runs and the evaluator page show. A description in a version’s own definition still wins.
`set_tags`	Destructive	Replaces the tags of an eval set, evaluator or run, by name; a new name creates a tag and `[]` clears them.
`archive_eval_set`	Destructive, owner or admin through sign-in	Hides an eval set from the active list; frozen versions and the runs that pin them stay readable.
`update_evaluator`	Destructive	Renames an evaluator or changes its description; versions, tags and check descriptions stay as they are.
`archive_evaluator`	Destructive, owner or admin through sign-in	Hides an evaluator from the active list; versions pinned on runs stay readable.

`runs`

Runs execute an eval set version’s cases; scoring runs score outputs that already exist.

Tool	Access	What it does
`list_runs`	Read	Lists runs, newest first, by eval set, creation window or tag; a run carries its own tags and matches its eval set’s, and its `execution_state` as Runs shows it.
`get_run`	Read	Returns per-evaluator aggregates, execution counts, `execution_state` and `progress` (every case settled, running or needing recovery; scoring pending), with up to 25 failing cases first and, against `baseline_run_id`, paged case-level regressions and improvements. `sim_gaps`, in the summary and on each failing case, lists simulation gaps.
`add_run`	Write	Creates a run on a frozen eval set version with 1 to 100 pinned evaluator versions.
`list_run_items`	Read	Lists a run’s cases with their latest execution state.
`get_run_item`	Read	Returns one case of a run; inputs and expected values with `include_content: true`.
`get_run_execution`	Read	Returns one execution attempt’s state, times, error, the trace it declared, its output files and each pinned evaluator’s result; the recorded output and evidence with `include_content: true`.
`start_run_case`	Destructive	Starts or retries one case of a run.
`complete_run_case`	Destructive	Marks a started execution succeeded, errored or cancelled; a success carries its output.
`finish_run`	Destructive	Seals a run once every case’s latest execution has ended.
`list_scoring_runs`	Read	Lists scoring runs, newest first.
`get_scoring_run`	Read	Returns one scoring run’s pinned evaluator versions, seal time and a page of its items: each `scoring_item_id`, which `add_scoring_results` and `add_judge_jobs` take, with every evaluator’s result or `pending`; hosted judge jobs with `include_judge_jobs: true`.
`add_scoring_run`	Write	Creates a sealed scoring run with pinned evaluator versions over existing outputs or a run’s completed cases, without running the agent, and returns its items. Hue scores the evaluator kinds it runs itself; record the rest with `add_scoring_results`.
`add_scoring_results`	Write	Records evaluator results on a scoring run.
`update_run`	Destructive	Renames a run; its eval set version, results and tags stay as they are.

`judges`

World judges and hosted judge jobs.

Tool	Access	What it does
`list_judge_results`	Read	Lists a world judge’s scored results with verdicts, reasons, promotion state and label counts.
`get_judge_alignment`	Read	Reports how a judge version agrees with people’s labels against the project’s bar, and compares two versions.
`label_judge_result`	Write	Agrees or disagrees with one verdict, with an optional note; your latest label counts.
`set_judge_promotion`	Destructive	Promotes a judge version that meets the bar, so its verdict decides cases, or demotes it to advisory.
`check_judge_regression`	Write	Rescores a judge version on labeled executions, without running the agent, and compares it with an earlier version.
`set_judge_alignment_bar`	Destructive, owner or admin	Changes the bar a judge version must meet to be promoted.
`get_judge_budget`	Read	Reports the project’s hosted-judge configuration and usage, and the organization’s monthly AI budget as `organization_budget`.
`add_judge_jobs`	Write	Queues hosted judge jobs for scoring-run items.
`cancel_judge_jobs`	Destructive	Cancels hosted judge jobs: a queued job stops without charge, a running one may still finish and be charged, and a finished one is unchanged.

`cases`

Cases built from traces, from a single trace or in bulk from Suggested cases. See Create a case.

Tool	Access	What it does
`list_cases`	Read	Lists cases reviewed from traces, drafts and published, with links.
`get_case`	Read	Returns one reviewed case with its eval set, saved version, pinned evaluators, environment and a run block; task text with `include_content: true`.
`get_case_conversion_eligibility`	Read	Checks whether a trace revision, or one of its span subtrees, can start a case build, with its blockers and whether the case could publish, without model calls or writes.
`add_case_conversion`	Write	Builds a case from a trace revision with optional outcome feedback. It publishes when its source and evaluator definitions are valid unless `publish_when_ready` is `false`.
`get_case_conversion`	Read	Returns a draft’s readiness, findings, evidence and criteria summary; its task, starting World and criteria with `include_content: true`.
`update_case_conversion`	Destructive	Edits a draft: its JSON fields, facts and acknowledgements, and for a case built from a trace, the review actions.
`publish_case_conversion`	Destructive	Publishes a ready draft into a new eval set or an existing draft version.
`archive_case_conversion`	Destructive	Abandons a draft; a published case cannot be archived.
`get_case_divergence`	Read	Shows where a run of a case built from a trace first went differently from its source trace.
`list_suggested_cases`	Read	Ranks groups of production requests by what a case would add.
`add_case_conversion_batch`	Write	Builds one case per trace revision of a Suggested-case group. Each publishes when its source and evaluator definitions are valid, as with `add_case_conversion`; one that stops short stays a draft.
`get_case_conversion_batch`	Read	Reports a bulk conversion’s status and every item’s draft and build state.
`update_case_conversion_batch`	Destructive	Retries failed items, cancels a bulk conversion or resumes one that stalled.

`runners`

Connected agents (local workers, managed targets and GitHub deployments), their dispatches, and artifacts.

Tool	Access	What it does
`list_agents`	Read	Lists every agent a run can be dispatched to: local workers (`hue eval --worker`), managed targets and connected GitHub deployments, with availability, capabilities, revision and source; never credentials.
`refresh_agents`	Write	Refreshes the connected GitHub repositories’ deployments, then lists every agent as `list_agents` does.
`preflight_run`	Read	Checks whether an agent can run every case of a saved eval set version before `launch_run`: counts, `can_launch`, the blocking reason and each unsupported case’s reasons.
`launch_run`	Write	Creates a run on a saved eval set version and dispatches it to an agent from `list_agents` in one call, under an idempotency key; answers what to poll, the terminal states and the recovery tool.
`add_managed_target`	Write, owner or admin	Registers a managed target; its credential is stored encrypted and never returned.
`get_managed_run`	Read	Reports a managed dispatch’s status, target and case counts for the whole run, and a page of its cases; case names and previews with `include_content: true`.
`cancel_managed_run`	Destructive	Cancels a managed dispatch; cases in flight may still finish.
`get_local_run`	Read	Reports a local run’s status, whether its worker’s claim is stale and whether a requeue would be accepted.
`recover_local_run`	Destructive	Recovers a local run with the same checks as the run page: `release` a stale claim, which moves the run to attention; `requeue` a run in attention when `get_local_run` says `requeueable`; `relaunch` a run in attention as a new run with the same pinned versions and config; or `cancel` a run that has not completed.
`list_artifacts`	Read	Lists artifacts and the storage allowance; bytes stay on HTTP.
`get_artifact`	Read	Returns one artifact’s metadata.

`worlds`

Worlds: authored definitions and their versions (world_definition_id, world_version_id), trace builds and their uploads, retained World models, and the simulated apps. The debug profile lists the tools for building a World from one trace and trying it.

Tool	Access	What it does
`list_worlds`	Read	Lists Worlds.
`get_world_definition`	Read	Returns a World’s versions, and one version’s definition and actions with `world_version_id`. A World built from a trace returns its definition only with `include_content: true`, and a definition too large for one result pages by `definition_offset`.
`update_world`	Destructive	Replaces a World’s display title, description or both; omitted fields stay unchanged. Archived Worlds cannot be changed.
`publish_world_version`	Write	Publishes an immutable version from an authored definition, including custom actions, on an existing World identity.
`get_world_overview`	Read	Counts a World version’s app records and reports their dating fields, earliest and latest dates, and weekly spread. Optional `select` counts matching records, lists IDs, or groups field values. Listed records and group values require `include_content: true`.
`get_world_edit_context`	Read	Returns collection bindings and record schemas for a World version or a running `instance_id`. Live inspection includes `step_count`. Select a collection and use `include_content: true` for bounded, redacted, audited records.
`edit_world`	Write	Publishes a new version with app and record changes from a `description` or explicit `changes_json`, or changes records in a running `instance_id` immediately using explicit operations. Requires an idempotency key. `dry_run` validates without changing data; `expected_step_count` can guard live edits. See Change starting data for future runs and Change records while an agent runs.
`archive_world`	Destructive	Stops a World being attached to new cases; versions already pinned stay readable.
`prepare_trace_upload`	Write	Reserves a private trace or context upload for 15 minutes, with an exact size and SHA-256, for `create_world_from_trace`. Each object can contain up to 25 MiB.
`complete_trace_upload`	Write	Verifies an upload’s original bytes against its size, checksum, purpose and project before a build can use it.
`create_world_from_trace`	Write	Builds a World from one OTLP JSON or Langfuse observations export, up to 256 KiB inline or 25 MiB through an upload, and optional context. Publishes it and starts a four-hour instance once the build is ready; building sends trace content to models (AI processing). A stored trace with `retained` World capture needs no build (start an instance).
`get_world_build`	Read	Returns build progress, counted evidence gaps, a bounded incomplete reason, source checksum and published World, version and instance IDs. Returns no source content or token.
`retry_world_build`	Write	Resumes an eligible interrupted or failed build while preserving completed stages and model allowances. Exhausted budgets and unknown interrupted model spending remain incomplete.
`prepare_world_import`	Write	Reserves private upload URLs for app records with each file’s size and SHA-256. Upload the exact bytes within 15 minutes, then call `publish_world_import`.
`publish_world_import`	Write	Checks an import’s uploaded files and publishes a World version in the background. On a ready import, publishes a fresh version from the same records.
`get_world_import`	Read	Reports an import’s progress, record counts by app account, failures, and the ready `world_version_id` to pass to `start_instance`.
`generate_world`	Write	Generates app data from a description and publishes a World version. Returns an outline and cost estimate first. `dry_run` previews without creating a World.
`get_world_generation`	Read	Reports generation progress, budget pauses, failures, and the ready `world_version_id`.
`create_world`	Write	Seeds the selected apps with empty data, uploaded records, or generated data from a description, then publishes a World version. Returns upload URLs when needed. Follow progress with `get_world_creation`, then call `start_instance` when ready.
`create_world_variation`	Write	Creates a separate, fuller World from an immutable version or a retained user World at a represented time, with up to eight selected traces. Preserves source facts and follows progress through `get_world_creation`. Source names and text reach models only with `share_samples: true`.
`get_world_creation`	Read	Reports creation progress, record counts by app account, failures, and the ready `world_version_id` to pass to `start_instance`.
`cancel_world_creation`	Destructive	Cancels an in-flight creation or variation and prevents publication. Calls already in flight may finish and incur charges. An already published creation returns a conflict.
`list_world_models`	Read	Lists retained World models: the captured history of each real entity with its name, readiness and evidence cutoff, most recently used first.
`get_world_model`	Read	Reads one retained World model through a bounded view: `summary`, `accounts` (the app accounts its history binds) or `instances` (historical instances started from it, each with its represented time and version, paged).
`get_world_apps`	Read	Reports what a World version’s simulated apps offer an agent: served connections, the operations each mirror simulates with a read or write flag, and declared gaps.
`list_apps`	Read	Lists the apps Hue simulates for Worlds with their surfaces and, where your organization may see them, a fidelity summary of counts and labels.
`get_app`	Read	Returns one simulated app by slug: its surfaces and, where your organization may see them, each surface’s catalog coverage, test tally, freshness and known limitations.

For a new World, create_world takes name, apps, and an idempotency_key. Reuse the key when retrying creation. It accepts neither raw definition_json nor a custom slug. Creation publishes a version; it does not start an instance.

`instances`

An instance is one running or saved World runtime; its tools take instance_id.

Tool	Access	What it does
`start_instance`	Write	Starts a fresh instance from an immutable World version (`world_version_id`) or from a retained World model at a represented UTC time (`world_model_id` and `at`), and returns its token and serving URLs once. For a version start, optional `time_window` selects records by date and returns the bounds, removed count, retained references, and dating fields. `ttl_seconds` defaults to four hours and accepts up to 24 hours. A World model still preparing answers `World is preparing`; Start an instance over MCP covers retries and refusals.
`list_instances`	Read	Lists a World version’s instances by `world_version_id`, with their `time_window`, clock, lifecycle, activity, and creation time. Continue with `cursor`; `limit` bounds the page.
`reproduce_instance`	Write	Starts a fresh instance from an earlier instance’s original starting World: the same World model, represented time and evidence cutoff, so a run reproduces after the earlier runtime was cleaned up.
`restart_instance`	Destructive	Finishes the previous attempt and creates a fresh instance and token from the same World version and time window.
`finish_instance`	Destructive	Finishes an attempt and retains its saved state, committed steps and request records.
`get_instance_connections`	Write	Explicitly reveals an active instance’s token, supported app URLs, protocols, credential placement and connection details, client settings included. The reveal is audited.
`get_instance`	Read	Returns a saved instance’s activity, lifetime, state version, step count and app bindings, including `collection_bindings` for state/diff selectors. Returns no token.
`get_instance_state`	Read	Reads bounded starting, current or sealed final data, with app, collection, entity and field selectors. Values require `include_content: true`. A collection’s `count` is `null` when the page is not the whole collection: it holds more rows than the page, the page continues from a `cursor`, or the read names `entity_ids`. `null` never means empty.
`get_instance_diff`	Read	Compares starting data with current or sealed final data. Returns changed IDs and fields by default; values require `include_content: true`.
`list_instance_steps`	Read	Reads committed steps in order; continue with `after_step`. Arguments, results and changes require `include_content: true`.
`list_instance_requests`	Read	Pages server requests and recording gaps for the instance, with optional app, search and time filters. Call content requires `include_content: true`.
`send_instance_input`	Write	Acts as a running Slack instance’s user: sends a message or thread reply, runs a slash command, clicks a button in a message or an open modal (`view_id`), submits a modal (`view_submission`, with `state.values` JSON in `text`), or opens the app’s Home tab (`app_home_opened`). A message’s `channel` can be the bot’s own user ID, which messages the bot directly. With `provider: "photon"`, texts a Photon iMessage line as a person, or sends a tapback, attachment or poll vote with `native_action` and `kind: "message"`. The Slack `action` string remains a button’s action id. The agent’s event subscription receives the input; a Slack message that reaches none returns `undelivered` with the reason, and every new input returns the instance’s `expires_at`. Inspect its reply with `get_instance_state`. Reuse `idempotency_key` when retrying.
`act_as_person`	Write	Makes a person in a live LinkedIn, X or Gmail instance act toward the agent, such as accepting an invitation or replying to a message. `at` or `in_seconds` schedules the action.
`create_notification`	Write	Adds a notification to the agent’s LinkedIn or X account, unread by default. A future `at` makes it visible when the World’s clock reaches that time.
`set_person_responses`	Destructive	Switches a LinkedIn or X person between automatic responses and responses controlled through `act_as_person`. Returning to automatic resumes only responses due after the switch.
`list_scheduled_events`	Read	Lists scheduled person actions and future notifications in a LinkedIn, X or Gmail instance. Due actions apply on the app’s next agent write or a clock jump.
`cancel_scheduled_event`	Destructive	Cancels a pending person action or a notification whose World time has not arrived, using its ID from `list_scheduled_events`.
`list_world_people`	Read	Lists a LinkedIn, X or Gmail instance’s people, their relationship to the agent, response mode and pending interactions.
`get_world_clock`	Read	Returns an instance’s current World time, start, seconds per agent write, clock jumps and step usage.
`set_world_settings`	Destructive	Changes a running instance’s LinkedIn or X account limits, plan or restrictions as an external event. `null` lifts a limit.
`set_world_step`	Destructive	Sets how far each later step advances a LinkedIn-and-X instance’s clock, from 0.001 to 86,400 seconds. Omitting the value restores the World’s original step size.
`advance_world_clock`	Write	Moves a LinkedIn, X or Gmail instance’s clock forward and applies due person actions and notifications. The agent sees the result on its next read.
`patch_world_record`	Destructive	Compatibility tool that adds, updates or deletes one record in a running instance. Refuses agent-written records. Use `edit_world` with `instance_id` for schema-guided batches and edits to agent-written records.
`save_instance_case`	Write	Saves a finished instance as an eval set case pinned to its World version, with deterministic checks drafted from its app calls and changes, or supplied in `criteria_json`. Defaults to the Saved interactions eval set. Returns the case, checks, and their result on this instance. A repeat and a windowed instance are refused.
`check_instance_case`	Write	Checks a finished instance against a case’s deterministic outcome criteria without a model. The instance must use the case’s World version. Returns each check’s outcome and an overall `pass`, `fail`, `inconclusive`, or `error` result.

For a model start, optional checkpoint_selection pins an existing preview’s selection with at, cutoff, interpretation_digest, and generation. Its at must match the start’s at. Reuse the selection and idempotency_key while preparation finishes. Without a selection, Hue selects the latest completed evidence when it admits the start.

`intents`

Listed by default: get_intent_summary, list_intent_traces and get_request_answer.

Tool	Access	What it does
`get_intent_taxonomy`	Read	Returns the project’s intent categories, empty when no taxonomy is saved.
`save_intent_taxonomy`	Destructive, owner or admin	Publishes a new version of the intent taxonomy.
`classify_pending_intents`	Write, owner or admin	Queues intent classification for a range’s traces that are still unclassified, as the Intents page’s recovery action does.
`get_intent_summary`	Read	Counts a window’s traces per intent bucket; with request answers, it also carries the `task_types` answer.
`list_intent_traces`	Read	Lists one intent bucket’s traces as `search_traces` rows.
`get_request_answer`	Read	Answers one question about the agent’s behavior across requests, or returns every finding with `overview`; see request-answer details.

`docs`

Listed by default: both tools. Each guide is also an MCP resource, hue://guides/<topic>, and the prompts triage_production, investigate_trace, case_from_trace (write access only) and evaluate start a workflow over one.

Tool	Access	What it does
`search_hue_docs`	Read	Searches docs.hue.run and returns titles, links and excerpts. Ask a product question; never paste recorded content.
`load_hue_guide`	Read	Returns one of Hue’s workflow guides as markdown: `data-model`, `production`, `investigate`, `author`, `evaluate` or `import`.

Catalog tools

Listed beside every toolset selection except all, which lists every tool directly instead. Code Mode also lists the catalog tools.

Tool	Access	What it does
`search_hue_tools`	Read	Finds the tools your access allows by keywords or toolset, 10 per page, with each tool’s access, input schema and how to call it.
`execute_hue_tool`	Read	Calls a read tool by name, with the same checks, audit and result as a direct call.
`execute_hue_write_tool`	Destructive	Calls a write tool by name. It is annotated destructive because it can call any write; approve each call as you would the write itself.

Recipes

The Hue MCP server reads stored traces, spans, findings, trace checks and intents, plus counts and percentiles. It does not diagnose; your agent analyzes the returned data. A Read key is sufficient. The default observe toolset includes most recipe tools. Find get_intent_taxonomy and trace-check reads with search_hue_tools, then call them through execute_hue_tool, or list all tools with ?toolsets=all. get_request_answer covers cross-request behavior for projects whose requests Hue maps. load_hue_guide with production returns this guide in MCP; resource clients also expose hue://guides/<topic>. triage_production (window, default 7d) and investigate_trace (trace) prompts appear in Claude Code as /mcp__hue__triage_production and /mcp__hue__investigate_trace. Use aggregate for counts and percentiles, search_spans for individual steps, and get_span_content for exact recorded values. search_traces and get_trace connect spans to requests. Each recipe is a short sequence of tool calls with their key arguments. Replace 24h with the window the user asked for. aggregate and search_spans read spans over at most 7 days; trace reads cover up to 90 days.

Before you start

Select the project. API keys and organization sign-in reach active projects in their organization. Confirm the project from list_projects and pass its id or slug as project_id. An API key can omit it to use its default project. Pinned connections omit that argument and report connection.pinned: true.
Keep the tool boundary consistent. Hue arguments and outputs use recursive snake_case; recorded attribute maps keep application keys. Object ids and result names use product terms, and app-page ids accept Hue links. JSON arguments that round-trip trace-check definitions, calibration or judge bars must use returned snake_case keys; camelCase is rejected.
State the method. Ask the agent to report its window, filters, traces opened and links; its analysis is not a Hue-generated diagnosis.
Report limits. aggregate and total_count cover the filtered window unless scan_capped, partial, total_capped or total_count_capped says otherwise. Search result pages are samples; state when the agent opens only a bounded sample.
Rankings use counts. aggregate returns the top 10 groups (up to 25), with the rest in other; filter or raise top to inspect rare groups.
Check empty results. A narrow window, filter or disabled feature can return nothing. get_project_context.features lists enabled features; widen the window or remove filters before concluding nothing happened.
Rows omit null or empty fields. Shared links may be returned once as a URL template.
Content is opt-in and audited. Request it with get_span_content or include_content: true only when needed; results mark recorded content as untrusted. See the security model.

Find traces that need attention

Prompt: “What needs attention in the last 24 hours, and why? Link the traces.” Sequence: get_project_context → aggregate with {"since": "24h", "group_by": ["attention_state"]} and {"since": "24h", "group_by": ["finding"]} → search_traces with {"since": "24h", "attention": "needs_attention"} or {"since": "24h", "status": "error"} → get_trace → get_span_content for exact evidence. Caveat: needs_attention includes findings and positive active trace checks; uncertain means Hue could not settle a finding.

Find failing tools

Prompt: “Which tools failed most often yesterday, and what was their failure rate?” Sequence: aggregate with

{"entity": "spans", "since": "24h", "kind": "tool", "group_by": ["tool"], "metrics": ["count", "error_count", "duration_p95_ms"], "top": 25}

→ search_spans with {"since": "24h", "kind": "tool", "status": "error", "name": "<span name>"} → get_span_content with {"attribute_keys": ["gen_ai.tool.call.arguments", "gen_ai.tool.call.result"]}. Caveat: Groups rank by call count, and span name may differ from tool name; an errored call does not prove the request failed. search_traces with "finding": "unrecovered_tool_error" lists traces where the agent did not recover.

Find slow tasks and steps

Prompt: “Which task types and steps were slowest this week?” Sequence: aggregate with

{"since": "7d", "group_by": ["trace_name"], "metrics": ["count", "duration_p50_ms", "duration_p95_ms", "duration_p99_ms"]}

→ aggregate spans with

{"entity": "spans", "since": "7d", "trace_name": "<name>", "group_by": ["name"], "metrics": ["count", "duration_p50_ms", "duration_p95_ms"]}

→ search_traces and search_spans with {"since": "7d", "trace_name": "<name>", "sort": "duration"} → get_trace_check_summary with {"since": "7d"}. Caveat: Intent grouping needs a published taxonomy; duration sorting includes completed traces only.

Measure time to first reply

Prompt: “How long did users wait for the first useful reply?” Sequence: aggregate with

{"entity": "spans", "since": "7d", "name": "<span that delivers the reply>", "group_by": ["trace_name"], "metrics": ["count", "start_offset_p50_ms", "start_offset_p95_ms"]}

gives the time until that span starts, per task type → search_spans with {"since": "7d", "name": "<span that delivers the reply>"} for individual reply-span rows → sum each row’s start_offset_ms and duration_ms for end time, then take percentiles of those sums. Caveat: Identify the reply span, which depends on the application, and page through every row in the window with next_cursor in the default newest-first order, or report a sample; a sort: "duration" page would skew it. Separate start-offset and duration percentiles cannot be added. With timing enabled, use search_traces.first_useful_answer_ms or get_trace_check_summary.requests for first-response, useful-playback, useful-server and completion p50 and p95 values.

Compare releases

Prompt: “Did the latest release regress?” Sequence: aggregate with {"since": "7d", "group_by": ["release"], "metrics": ["count", "error_count", "duration_p50_ms", "duration_p95_ms"]} → search_traces with {"since": "7d", "release": "<release>", "status": "error"} → get_trace to compare examples → aggregate with {"since": "<T minus 24h>", "until": "<T>"} and {"since": "<T>", "until": "<T plus 24h>"}. Caveat: Without a recorded release, compare rates in equal ISO-8601 windows around deploy time; concurrent releases can mix them.

List a user’s or session’s traces

Prompt: “Show user <id>’s traces and sub-agent activity from the last seven days.” Sequence: search_traces with {"since": "7d", "user": "<user id>"} or {"since": "7d", "user_prefix": "<user id>:"} → aggregate with {"since": "7d", "group_by": ["user"], "metrics": ["count", "error_count"]} → list_sessions with {"query": "<session key or part of it>", "since": "7d"} → search_traces by session_id. Caveat: Include the separator in a user prefix to avoid matching similar IDs; sessions group users only when the application records one session per user.

Find sub-agent handoffs

Prompt: “How does the agent hand work to sub-agents?” Sequence: inspect agent and handoff spans with get_trace or search_spans using {"since": "24h", "kind": "agent"}; follow separate roots by user, trace name, session or span links. Use search_traces with {"since": "7d", "check_key": "delegation"} for positive delegation trace-check results. Caveat: When parent IDs exist only in recorded content, read them with get_span_content.

Compare tool input and output sizes

Prompt: “Which tools return the largest results?” Sequence: aggregate with

{"entity": "spans", "since": "24h", "kind": "tool", "group_by": ["tool"], "metrics": ["count", "input_bytes_p50", "output_bytes_p95", "output_bytes_max"]}

→ search_spans for calls behind a maximum. Caveat: Byte counts are UTF-8 sizes of recorded JSON, without reading content.

Find traces by model or attribute

Prompt: “Find traces for model <model> or attribute app.plan=enterprise.” Sequence: search_traces with {"since": "24h", "model": "<model>"} or {"since": "24h", "attribute": {"key": "app.plan", "value": "enterprise"}} → search_spans for attributes on any span. Caveat: Trace model or attribute searches scan the newest 5,000 matches and report scan_capped; content attributes are refused.

Read span content

Prompt: “Show the exact tool arguments and result for <trace>.” Sequence: get_span_content with {"attribute_keys": ["gen_ai.tool.call.result"]} for trace and span IDs, then select fields, path or attribute_keys. Text uses UTF-16 slices with total_length and next_offset; omitted spans appear in omitted_span_ids. For a log record’s values, pass one span in span_ids, the ids of logs that get_span with include_logs: true listed in log_ids, and the log_cursor of that page, if any. fields are body, the default, and attributes. A span or log names the values Hue stored apart from it under blobs; pass one’s key, such as body#/details, in attribute_keys to read it whole. A value that holds only the first 16 KiB of one is marked partial, with its blob_keys. Caveat: Reads are audited and untrusted; each request reads up to 20 spans or logs, in 8,000-unit slices by default. Invalid paths report available keys.

Review trace check results

Prompt: “Which traces did the delegation check flag this week, and what evidence did it use?” Sequence: list_trace_checks → get_trace_check_summary with {"since": "7d", "check_key": "delegation"} → search_traces with {"since": "7d", "check_key": "delegation"} → get_trace_check_results with {"check_key": "delegation", "state": "present"}; follow next_cursor. See the trace-check data model for definitions and states. Caveat: Excerpts require include_content: true and are evidence, not explanations.

Data model

Request answers

get_request_answer answers questions about delegation, added_work, handoff_scope, data_cuts, slow_tasks, task_types and answer_time; overview returns every finding. By default it covers the last 7 days of production traffic only, for up to 90 days. environments: ["all"] and include_simulated: true include simulator traffic; program, model and release filter exactly. Each answer’s n counts requests, handoffs or reads. coverage reports eligible, judged, pending and provisional units, the share with complete evidence, and evidence gaps. Answers include environment and user splits and example requests with traces. limit defaults to 5 examples per finding (up to 25); more_call gets the rest, and finding returns one finding’s examples. group_by adds a series by day, release, model, program, environment, user or intent. notes lists caveats on the numbers; no notes means none. include_content: true adds example request text as untrusted, audited content. no_data means no mapped request matched the window and filters. When get_project_context.features.request_answers.available is false, Hue does not map the project’s requests; trace checks or spans answer these questions instead. Model judgments also require AI request judges.

Traces and spans

A trace is a root span and its tree; each span records one timed operation. In multi-agent apps, a trace may represent one agent activation rather than one user turn. Sessions group traces by the session id your application records. search_traces filters a window by status, attention, finding, check_key, user, user_prefix, release, trace_name, model, a root-span attribute, deployment_environment, run_traces, session_id, min_duration_ms and query (title, root span name or trace id), and sorts by started_at (newest first) or duration (longest first). It returns these fields per trace:

Field	Meaning
`id`, `trace_id`, `url`	Hue’s id, the 32-hex OpenTelemetry trace id, and the link to the trace in Hue, or `traces_url_template` beside the list when every row shares it. Every `trace_id` argument accepts all three.
`title`	Derived from the latest recorded request text, else a producer-supplied trace name, else the reply, else the root span name. Untrusted text.
`status`	`error` when any finished span has error status; else `ok` when any span is `ok`; else `unset`.
`execution_status`, `tool_error_count`	How the root span ended (`ok`, `error`, `cancelled` or `unset`), so a trace whose agent recovered reads `status: "error"` with `execution_status: "ok"`; and how many finished tool spans recorded an error. Each is left out when empty.
`state`	`running` while a span is open, `stalled` after 15 minutes without new data and no end, else `ended`.
`source`	`sdk` for application traffic, `experiment` for traces from evaluation runs, `playground` for playground runs.
`started_at`, `ended_at`, `duration_ms`	`duration_ms` is end to end and `null` while the trace is open.
`tokens`, `span_count`	Input and output token totals and the number of stored spans.
`session_id`, `session_key`	Hue’s session id, for `search_traces`, and your application’s session key.
`deployment_environment`	The deployment label your application recorded as `deployment.environment.name`, `deployment.environment` or `langfuse.environment`, on the root span or its resource; not one of Hue’s simulated environments. `search_traces` and `aggregate` filter by it exactly, and an empty string selects unlabeled traces.
`run_trace`	`true` when one of your runs recorded the trace; left out otherwise. See traces from runs.
`user_id`, `release`, `trace_name`	The user id, release and trace name your application recorded, each up to 200 characters and returned whole, so each works as a filter. See the field glossary.
`attention_state`, `finding_ids`, `check_state`	The attention state, the ids of the findings present, and the trace-check state. See attention states and findings and trace checks.
`first_useful_answer_ms`, `useful_answer_timing_source`, `request_start_source`	Request timing, for projects set up for it; otherwise `null`.

get_trace adds has_input, has_output and revision, run for a trace one of your runs recorded (the run’s id and name, the case_id, the execution_id that get_run_execution reads, and a link to the case result), world, the trace’s World capture (its state, and the reason for an unresolved or ineligible trace; see Why a trace added nothing to a World model), the stored findings (the assessment’s attention_state, items with each finding’s id, label, state, source and span_ids, and tool_errors with each error’s span, tool and error_type), the trace-check results as checks, and span rows in start order. Each span row has id, span_id, parent_span_id, name, kind, status, status_message, error_type, state, operation, tool, started_at, ended_at, duration_ms, model, tokens, input_bytes and output_bytes. A span’s kind is tool, agent, embedding or llm when Hue recognizes the operation. Otherwise it is the recorded operation name, such as chain, or the OpenTelemetry span kind, such as internal. A span’s status comes only from its OpenTelemetry status code. search_spans returns span rows from many traces with the same fields, plus the span’s trace_id and start_offset_ms, the time from its trace’s start to its own. It filters a window of up to 7 days by span name, kind, status, model, min_duration_ms and one attribute, and by the trace’s trace_name, user, user_prefix, release, session_id and run_traces; it sorts newest or longest first and reports total_count. When nothing matches a name or trace_name, it suggests the closest recorded names. get_span returns one span: status with its code and a message of up to 200 characters, model, usage (input, output, cache and reasoning tokens where recorded), gen_ai (operation, provider, response_model, agent_name, session_id, user_id and the detected profiles), tool (name and call_id), has_input and has_output, service, attribute_keys (the names of up to 100 recorded attributes, never their values) and event_names. When the result fits max_chars, it also carries the instrumentation scope, the dropped-attribute and dropped-event counts, and span links. get_span also lists up to 64 files: the images, audio and documents the span records. Each has its role and, where known, modality, media_type, name, size, sha256, a remote uri, a provider file_id, or langfuse_media_id for a file held in Langfuse. A file whose bytes the span lists under hue.blobs also has its key and state: stored, missing (never uploaded, or erased) or unavailable. With include_content: true, each stored file, and each file held inline as a data: URL or base64 part of up to 1 MiB, adds download_url, a link valid for five minutes, and download_expires_at; with include_logs: true as well, so do the files of each log on the page. A script with a Read or Read and write key gets the same link from the trace file endpoint.

Traces from runs

A trace that one of your runs recorded while executing a case is a run trace, whatever deployment label it carries, so a run against your staging deployment keeps deployment_environment: "staging". search_traces, search_spans, aggregate and list_sessions leave run traces out unless run_traces says otherwise, so a question about production or staging traffic counts what your users did:

`run_traces`	Keeps
omitted or `exclude`	Every trace except run traces.
`include`	Every trace, run traces included.
`only`	Run traces alone.
a run id or link	That run’s traces alone.

To compare what the agent did across runs, call aggregate or search_spans once per run id, for example tool calls and errors per tool. An empty search_traces page that left run traces out says how many in hint. A session that holds any run trace counts as a run session. Reads by id (get_trace, get_span, get_run_execution) return run traces whatever the filter, and the Traces page in Hue follows the same default, with Filter > Run traces to include them or show only them.

Aggregates

aggregate counts a window’s traces (the default), or its traces’ spans over at most 7 days. It filters by status, attention, check_key, session_id, deployment_environment, user, user_prefix, release, trace_name, name (for traces, the root span’s), min_duration_ms and run_traces. Span aggregates also filter by kind, model and tool, and refuse attention and check_key.

group_by takes up to two dimensions. Traces group by trace_name, name (the root span’s), status, attention_state, finding, intent, user, release and bucket; spans by trace_name, name, kind, status, model, tool, user, release and bucket. bucket is a time series of 5m, 15m, 1h, 6h or 1d buckets, at most 96, and counts as one of the two dimensions. intent needs a published taxonomy.
metrics, up to 8: count (always returned), error_count, duration_p50_ms, duration_p95_ms, duration_p99_ms, input_tokens and output_tokens; for spans also start_offset_p50_ms, start_offset_p95_ms, input_bytes_p50, input_bytes_p95, input_bytes_max, output_bytes_p50, output_bytes_p95 and output_bytes_max.
rows hold the top groups by count (10 by default, up to 25); other totals the rest and group_count counts every group. A group’s value is the recorded string, so it works as a filter, and a null group holds the traces or spans that recorded none. total counts the filtered window as search_traces does.
A trace aggregate reads the window’s newest 300,000 traces and says scan_capped and covered_since when the window holds more. A span aggregate reads its whole window. A part that runs out of time returns partial: true with timed_out.

Attention states and findings

By default, Hue assesses each quiet, ended production trace. Evaluation-run traces are not assessed. attention_state is:

State	Meaning
`needs_attention`	At least one finding is present, or an active trace check has a current positive result.
`uncertain`	No finding is present, but one could not be settled.
`rules_only`	Only the rule findings ran; the model pass did not run for this trace.
`no_findings`	No findings in the recorded evidence.
`not_assessable`	The trace recorded no readable request, reply or tool calls.
`dismissed`	A member dismissed the assessment’s findings in Hue.
`null`	Not assessed yet, or an evaluation-run trace.

The attention filter of search_traces takes needs_attention or uncertain, and finding takes one finding id. The findings are:

Finding	Source	Present when
`unrecovered_tool_error`	Rule	A tool returned an error and no later call to that tool succeeded.
`model_error`	Rule	A model call ended in error and no later model call succeeded.
`missing_reply`	Rule	No assistant reply text was found.
`possible_inability`	Model	The reply appears to say the agent could not do this or lacked access or a capability.
`possible_unresolved`	Model	The reply appears to address something other than the request, without answering or asking for input.
`possible_unsupported_completion`	Model and rule	The reply appears to say the action was done, but no recorded tool call succeeded, or a tool it called failed with no later success.
`possible_action_not_taken`	Model and rule	The request asks for an action, the reply neither reports it done nor asks for input, and no recorded tool call succeeded.
`unnecessary_delegation`	Request check	The main agent handed off work a sub-agent finished quickly, with no other sub-agent alongside.
`missed_delegation`	Request check	The main agent kept a long request instead of handing it off.
`over_latency_budget`	Request check	The request went over its model-call or output-token limit, counting its sub-agents.

Model findings come from the model pass that AI processing describes. Request-check findings appear only in projects where Hue has set up request checks; there they decide the attention state of each request’s main-agent trace. finding_ids lists present findings; get_trace returns their state, source and span IDs. stale: true means newer spans arrived after assessment. findings.judge_state and skip_reason explain when the model did not judge a trace.

Trace checks

Trace checks are project-owned, versioned checks of production behavior. They are advisory, not evaluator scores. The four checks are delegation (execution stayed with the orchestrator instead of a sub-agent), action_scope (execution expanded the request), delegation_scope (a handoff expanded the request) and output_omission (needed tool information was omitted). They produce results only after a project sets them up: instrumentation that marks the request and its boundaries, and a version activated against labelled traces. A result is present, absent, uncertain, unavailable (not enough evidence) or not_applicable. A trace’s check_state is needs_attention, pending, uncertain, unavailable, not_applicable, no_findings or null when no active version applies to it.

Intents

Intents classify traces into the project’s taxonomy of task types. get_intent_summary returns total, coverage and buckets, and consent, which is always true. Bucket keys are category:<key>, other, uncertain, no_user_text, failed and pending (not classified yet). Classification needs a published taxonomy (get_intent_taxonomy returns null without one). get_intent_summary and list_intent_traces take since and until and default to the last seven days. list_intent_traces returns the same trace rows as search_traces, with the summary’s total_count; follow next_cursor with the same window and bucket. aggregate groups traces by intent for durations and error counts per task type.

Field glossary

Hue reads these span attributes into its fields. When several are present, the first one listed wins, so the OpenTelemetry GenAI attribute wins over a Langfuse one. Hue reads only span attributes, with two exceptions: a trace’s release also takes service.version from the resource, and a span that names no user gives the trace’s user_id its resource’s user. get_span returns service.name as service. A trace’s user_id, release and trace_name are its root span’s, else those of the earliest span that has one; user_id never comes from a tool span or a span beneath one. Each is stored whole up to 200 characters. search_traces, search_spans and aggregate filter by them exactly with user, release and trace_name, user_prefix matches the start of user_id, and aggregate groups by user, release and trace_name.

Hue field	Span attributes, highest precedence first
User id (`user_id` on trace rows, `gen_ai.user_id` on spans)	`user.id`, `enduser.id`, `hue.user.id`, `ai.telemetry.metadata.userId`, `langfuse.user.id`, `enduser.pseudo.id`, `mlflow.trace.user`, `mastra.metadata.resourceId`; then a `userId`, `user_id` or `langfuse_user_id` field of the metadata maps below the table; a bare `user_id` last
Release (`release`)	`service.version` on the span, then on its resource, then `langfuse.release`, then `hue.agent.release`
Trace name (`trace_name`)	`hue.trace.name`, `langfuse.trace.name`
Session	`gen_ai.conversation.id`, `session.id`, `hue.session.id`, `ai.telemetry.metadata.sessionId`, `langfuse.session.id`, `mlflow.trace.session`; then a `sessionId`, `session_id`, `threadId`, `thread_id`, `conversationId`, `conversation_id`, `convoId`, `convo_id` or `langfuse_session_id` field of the metadata maps below the table; a bare `session_id` last. The trace’s session is its root span’s, else the earliest span that has one.
Agent name (`gen_ai.agent_name`)	`gen_ai.agent.name`, `ai.telemetry.functionId`, `traceloop.entity.name`
Operation, which sets the span `kind`	`gen_ai.operation.name`, `openinference.span.kind`, `traceloop.span.kind`, `ai.operationId`, `operation.name`, `langfuse.observation.type`
Model	`gen_ai.response.model` or `ai.response.model`, else the requested model: `gen_ai.request.model`, `llm.model_name`, `ai.model.id`, `langfuse.observation.model.name`
Provider	`gen_ai.provider.name`, `gen_ai.system`, `llm.provider`, `llm.system`, `ai.model.provider`
Input and output tokens	`gen_ai.usage.input_tokens` and `output_tokens`, then the `prompt_tokens` and `completion_tokens` forms, `llm.token_count.prompt` and `completion`, `ai.usage.*`, and last `langfuse.observation.usage_details`
Tool name and call id	`gen_ai.tool.name`, `tool.name`, `ai.toolCall.name`; `gen_ai.tool.call.id`, `tool_call.id`, `ai.toolCall.id`
Tool arguments and result (content)	`gen_ai.tool.call.arguments`, `ai.toolCall.args`, `tool.parameters`; `gen_ai.tool.call.result`, `ai.toolCall.result`
Messages (content)	`gen_ai.input.messages` and `gen_ai.output.messages`, OpenInference and OpenLLMetry message attributes, `ai.prompt` and `ai.response.*`, `input.value` and `output.value`, and last `langfuse.observation.input` and `output` and `langfuse.trace.input` and `output`
Error type (`error_type`)	`error.type`
Trace title	Derived from recorded request text first; the trace name is the fallback

Spans from the other instrumentations Hue normalizes fill the same fields from their own attributes. Hue reads the user and session from these metadata maps, in this order: ai.telemetry.metadata (Vercel AI SDK), ai.settings.context (AI SDK 7 runtime context), Raindrop’s ai.telemetry.metadata.raindrop and ai.telemetry.metadata.raindrop.ai, traceloop.association.properties (Traceloop and OpenLLMetry), Raindrop’s ai.telemetry.metadata.traceloop.association.properties, langfuse.trace.metadata, langfuse.observation.metadata, langsmith.metadata, braintrust.metadata, mastra.metadata and OpenInference’s metadata. Hue reads a field flattened (<map>.<field>) or from one JSON object recorded under the map, and decodes a JSON-encoded string value, as Langfuse’s SDKs write metadata. A user or session ID is a non-blank string or an integer. A Claude Code user.id recorded beside user.account_uuid names an installation, not a user, so Hue skips it for the next key, such as enduser.id. Langfuse metadata (langfuse.observation.metadata.*, langfuse.trace.metadata.*), langfuse.environment, tags and levels are kept as raw attributes. get_span lists their names in attribute_keys; get_span_content with attribute_keys reads their values, and the attribute filter matches the ones that are not content or free text. The OpenTelemetry guide lists the attributes worth recording so these fields are filled.

Limits and errors

Limit	Value
Time windows	`since` and `until` take ISO-8601 or relative values from `15m` to `90d`. Trace reads span at most 90 days; `search_spans` and span aggregates at most 7 days. Intent reads and `get_trace_check_summary` default to the last 7 days; `list_runs` and `reassess_trace_checks` take the same window form.
Page sizes	`search_traces`, `list_sessions` and `list_intent_traces` return up to 50 rows, 25 by default. `list_cases` and a `get_eval_set` case page return up to 50 (`get_eval_set` 10 by default). `search_spans`, `get_trace_check_results` and most other list tools return up to 100. Pass `next_cursor` back unchanged as `cursor`, with the same `sort`.
Spans per `get_trace` call	`max_spans` from 1 to 500, 200 by default; pass `next_span_cursor` back as `span_cursor`. A trace that changes between pages answers `conflict`; start again without the cursor.
Aggregates	Up to 2 `group_by` dimensions, 8 metrics, 25 groups (`top`) and 96 time buckets. Trace aggregates read the window’s newest 300,000 traces; span aggregates read their whole window.
Filter scans	`model` and `attribute` on `search_traces` read the newest 5,000 matching traces and say `scan_capped: true` when they stopped early. `search_spans` filters its whole window.
Result size	`max_chars` from 1,000, 24,000 by default; any value above 80,000 counts as 80,000, about what clients accept in one result. A list or span tree that does not fit returns the rows that do, with `omitted_count` and a cursor for the rest (`next_cursor`, or `next_span_cursor` on `get_trace`). `aggregate` keeps whole groups and reports `omitted_count` and `omitted_groups`. `truncated: true` with a `hint` means content, detail or groups were left out, or a single row did not fit.
Content reads	`get_span_content` reads up to 20 spans of one trace, or 20 logs of one span, per call, in slices of 8,000 UTF-16 units by default.
Counts	`total_count` counts up to 10,000 traces; beyond that `total_count_capped` is `true`.
Query time	Searches have a 2-second budget; a slower one fails with `timeout`. An `aggregate` part that runs out of time returns `partial: true` with the rest.
Request size	1 MiB; a larger body answers HTTP `413`.
Tool search and writes	`search_hue_tools` returns 10 tools per page. `add_eval_set_cases` takes 1 to 25 cases per call, `add_run` pins 1 to 100 evaluator versions, and `get_run` pages failing cases 25 at a time with `failing_cases_cursor`.
Text caps	Titles and names are capped at 200 characters, session keys at 128 and status messages at 200.

A tool that fails returns an MCP error result (isError: true) whose text starts with a code, then the message, sometimes a hint, and Retryable. or Retryable after <n> ms. when a retry can succeed, for example timeout: The query exceeded its time budget. Narrow the window … Retryable. The same fields (code, message, hint, retryable, retry_after_ms) are in the result’s _meta under hue.run/error for clients that read them programmatically. Retry only when the error says so. A write that is not safe to repeat and fails with unavailable or timeout may already have completed: its error does not say Retryable., and its hint says to read the write’s state before trying again.

Code	Meaning	Retry?
`invalid_argument`	An argument, window or cursor is invalid, such as a span window over 7 days or an `attribute` key that records content.	No: fix the argument.
`not_found`	No such object in this project. Ids from other projects answer this too, as does a `project_id` the connection cannot reach; call `list_projects`.	No.
`conflict`	The object changed, or the cursor belongs to another object or version. A fact addition refused by the monthly AI budget also answers `conflict`, with a message that says so.	Reload, then retry; after a budget refusal, wait until the budget has room.
`content_not_captured`	The application recorded this trace without content.	No.
`timeout`	The query exceeded its time budget.	Yes, with a narrower window or a lower `limit`.
`rate_limited`	Too many requests for this operation.	Yes, after about a second.
`unavailable`	A transient failure.	Yes.
`docs_unavailable`	The documentation search is unavailable.	Yes.
`judge_unavailable`	Hosted judging is not configured in this deployment, or the organization’s monthly AI budget is used up; `get_judge_budget` shows which.	Not until the cause changes.
`forbidden_capability`: `<tool> is not listed on this connection`	Your access allows the tool, but the connection’s toolsets do not list it. The hint names the executor that reaches it.	Not as sent: call it through `execute_hue_tool` (reads) or `execute_hue_write_tool` (writes), or add `?toolsets=<group>` or `?toolsets=all` to the server URL and reconnect.
`forbidden_capability`, any other message	An owner or admin must make this change; the key has no verified creating member; a connected app cannot create project keys; the connection cannot write; or the service refused the action.	No: ask an owner or admin, use a Read and write key, or make the change in Settings.
`read_only_mode`	The request is read-only, from `?read_only=true` or the `X-Hue-MCP-Read-Only` header, which hides and rejects writes.	No: remove both on a connection with write access.

For Read access, or a read-only request (read_only on the URL or the X-Hue-MCP-Read-Only header set to any value but false, 0, no, off or empty), write tools and execute_hue_write_tool are not registered at all: a direct call to a write fails as an unknown tool, and naming one to execute_hue_tool answers not_found. On a connection with write access, an executor given a tool of the other access answers invalid_argument naming the right executor. At the HTTP level, a busy server instance answers 503 with Retry-After: 1; retry after a second and keep parallel tool calls to a few. Ten failed authentications for one key within a minute answer 429 with Retry-After: 60. A request body over 1 MiB answers 413, and one that is not application/json answers 415. A JSON-RPC batch, a JSON array of messages, answers 400 without running any of them, so send one message per request. The connection guide’s troubleshooting covers these and the authentication errors.

World build gap codes

get_world_build counts what the trace left out as gaps, each with a code, a count and sample references, and Hue returns a sentence beside each code. Case eligibility reports the unmapped-call codes in world.gaps.

Group	Codes
Evidence the trace didn’t record	`no_execution_root`, `task_not_recorded`, `content_not_recorded`, `call_arguments_not_recorded`, `call_result_not_recorded`, `call_result_partial`, `call_arguments_partial`, `call_server_not_recorded`, `call_without_execution`, `call_order_uncertain`, `call_request_ambiguous`, `call_http_request_ambiguous`, `error_message_not_recorded`, `tool_catalog_not_recorded`, `tool_catalog_names_only`, `server_catalog_not_recorded`, `file_bytes_not_linked`, `file_not_uploaded`, `missing_parent_span`, `dropped_telemetry`, `spans_rejected_at_cap`, `spans_dropped_by_sdk`, `span_content_capped`, `actor_not_recorded`, `workspace_not_recorded`, `earlier_turn_input_not_recorded`, `worker_trace_not_recorded`, `reply_not_recorded`
Why a call reached no simulated app	`unidentified`, `internal_service`, `no_identity_rule`, `ambiguous`, `no_arguments`, `unknown_operation`, `unsupported_operation`, `untranslatable_arguments`, `untranslatable_result`, `identify_failed`, `result_not_recorded`
Replay and simulation	`opaque_failure`, `mismatch`, `gap`, `skipped`, `executed_unverified`, and codes that start with `sim:`

Hue reports any other code as unknown_ followed by a digest.