Tools Reference

Semaphor MCP has 21 tools in ten families. Each session sees only the tools its caller can use, so most sessions list fewer. Every tool name on these pages links here, and each tool's argument table is read from the server's own tool list, so it always matches the tool.

Who Sees Which Tools

Every session gets the session context, semantic discovery, governed query and dashboard tools, and semaphor_report_problem. The rest depend on who is calling:

Hiding a tool is for clarity, not the security control: the server authorizes every call. An argument that reaches physical tables or SQL inside a tool every caller sees (a physical source in semaphor_matrix, for example) returns capability_required for a session without SQL. Call semaphor_get_access_context when a tool you expected is missing.

Common Arguments

Argument names are camelCase. A tool rejects an argument it doesn't define and names it in the error, so a misspelled argument is never silently ignored:

MCP error -32602: Input validation error: Invalid arguments for tool semaphor_get_analysis_context: Unrecognized key(s) in object: 'question'

Session

semaphor_list_projects

Lists the projects you can access. Available only in interactive sessions.

semaphor_get_access_context

Reports who the session is and what it can do. Call it when a tool you expected is missing.

Returns: actorType (organization or tenant), userId, organizationId, projectId, projectCount, accountProjectListingAvailable, scopeSummary (one sentence), mode (org_interactive, org_headless or tenant_embedded), credential, scopes and capabilities.sql. End-user sessions add tenantId and the token's semanticDomainAccess.

{
  "actorType": "organization",
  "projectId": "p_abc123",
  "mode": "org_headless",
  "credential": "mcp_project_token",
  "scopes": ["mcp:read"],
  "capabilities": { "sql": true },
  "accountProjectListingAvailable": false
}

Semantic Discovery

semaphor_get_analysis_context

The first call for any data question. It checks the semantic domains the caller can see and recommends where to go next.

Returns: recommendedPath, recommendedNextTool, defaultAnalysisTool, fallbackAnalysisTool, guidance, semanticDomains, semanticDomainCount, fallbackConnections, projectId, projectCount, scopeSummary, actorType, mode and credential.

recommendedPath is one of:

{
  "projectId": "p_abc123",
  "semanticDomainCount": 3,
  "recommendedPath": "semantic",
  "recommendedNextTool": "semaphor_list_semantic_domains",
  "defaultAnalysisTool": "semaphor_analyze",
  "fallbackAnalysisTool": "semaphor_query_sql_advanced",
  "guidance": "Use semantic domains first for business questions. Then call semaphor_list_datasets for the chosen domain...",
  "semanticDomains": [{ "id": "dom_abc", "name": "sales", "label": "Sales" }]
}

semaphor_list_semantic_domains

Lists the semantic domains the caller can see.

Returns: domains, each with id, projectId, name, label, description, createdAt and createdBy.

semaphor_list_datasets

Lists the datasets in a semantic domain. Call it before semaphor_get_dataset_schema so the agent never guesses dataset names.

Returns: datasets, each with name, label, description, analyticsRole (such as fact or dimension), type, domainId, and connection metadata (connectionId, connectionType, dialect, database, table).

semaphor_get_dataset_schema

Returns the fields of a semantic dataset, or the columns of a physical table.

• Semantic mode (preferred): pass domainId and datasetName. Any connectionId passed along is ignored.
• Physical mode: pass mode: "physical" or connection coordinates (connectionId or connectionName, with databaseName, schemaName and tableName as the connection needs). Physical mode needs SQL access.

Returns: dataset (its source), fields, recommendedNextTool and toolChoiceGuidance. Each field has name, label, dataType, modelRole (fact, dimension or identifier), fieldKind and description; with the standard detail it also carries its source and a grounded fieldRef. With "responseDetail": "compact" a field leaves both out, since the dataset's location is in dataset once; name a field in a query as { "name", "datasetName" }. In semantic mode with the standard detail, reachableDatasets previews related datasets one join away, with example refs such as { "name": "supplier_name", "datasetName": "dim_supplier" }. A field also carries its aiContext (instructions, synonyms and example questions), and its format and isDisplayField when set: some of the values a semantic model change replaces; the proposal's own lines show the rest.

{ "domainId": "dom_abc", "datasetName": "orders", "responseDetail": "compact" }

semaphor_get_domain_relationships

Returns the relationships between datasets in a semantic domain. Useful before multi-dataset questions.

Returns: relationships, each with id, name, from, to, cardinality, defaultJoinType, isAutoJoin, joinPriority, confidence, isActive and description.

Physical Discovery

These tools need SQL access. Use them when the project has no semantic coverage for the question. Follow the capabilities semaphor_list_connections returns through the database and schema levels each connection needs.

semaphor_list_connections

Returns: connections, with ID, name, type, dialect and the discovery levels each one has.

semaphor_list_databases

Returns: databases (databases or catalogs).

semaphor_list_schemas

Returns: schemas.

semaphor_list_tables

Returns: tables with exact coordinates. Pass nameCandidates when you have likely entity names, such as ["orders", "order_lines"].

Governed Queries

semaphor_analyze

The default query tool. It runs governed analytics over a semantic domain: metric by dimension, top-N, time series, filters, date windows counted from now or from the newest row, period comparisons, period-change driver analysis, and joins through modeled relationships. Every call applies the caller's security policies.

Measures and fields. Measures are names or refs such as { "name": "revenue", "datasetName": "orders" }; a ref may add aggregate to override the modeled aggregate for this call, and "__count" counts rows. Dimensions and dateField take names or refs, including fields on related datasets.

Time windows. A timeWindow takes the same date windows a dashboard's date filter saves, so an answer and a dashboard on the same window show the same dates. Every periods and rolling window states its anchor, the point it counts from:

• "now": when the query runs.
• "latest_data": the newest row's date in dateField.
• { "lastComplete": "month" }: the end of the last complete month (or day, week, quarter, year).

• periods counts whole days, weeks, months, quarters or years. from and to count from the anchor's period: 0 is that period, -1 the one before it. Add "toDate": true to stop at the anchor instead of the period's end.
• rolling counts n units of elapsed time back from the anchor. Minutes and hours are rolling only.
• monthDay is the first or last day of the current month.

A window in any other form is refused. The refusal says what's wrong, and its fix lists the windows to send instead. When the nearest windows mean different things, the fix lists each one: ask your user which they mean.

Comparisons and drivers. comparison is { "kind": "previous_period" }, { "kind": "previous_year" } or { "kind": "target", "targetValue": 100000 }, stated once for the analysis, at the top level or the same on each measure that states it. A measure also takes a table calculation, transform (see What a Number Means). analysis: { "kind": "period_change" } finds spikes, declines and period-over-period moves, ordered by analysisOrderBy. driverMode picks which drivers a comparison returns. See Metric Comparisons.

{
  "domainId": "dom_abc",
  "datasetName": "orders",
  "measures": [{ "name": "revenue", "datasetName": "orders" }],
  "dimensions": [{ "name": "region", "datasetName": "customers" }],
  "dateField": { "name": "order_date", "datasetName": "orders" },
  "timeWindow": { "kind": "periods", "unit": "month", "from": -3, "to": -1, "anchor": "latest_data" },
  "limit": 10
}

Returns:

{
  "answerSummary": "Successfully executed query spec (5 rows).",
  "data": {
    "records": [
      { "Region": "West", "Revenue": 1758699.06 },
      { "Region": "East", "Revenue": 1670049.2 }
    ],
    "rowCount": 5,
    "rowLimitExceeded": true
  },
  "executionResult": {
    "status": "answered",
    "resultShape": "records",
    "constraints": {
      "applied": [
        { "kind": "filter", "field": { "name": "orders.order_date", "label": "Order Date" }, "operation": "between",
          "values": ["2026-09-17", "2026-10-17"], "valueType": "date", "timezone": "America/Chicago" }
      ],
      "skipped": []
    },
    "coverage": { "answeredObligations": ["governed_query_executed"], "missingObligations": [] }
  }
}

executionResult.constraints says what the query applied:

• applied: each filter it ran with (field, operation, and values as executed; a relative date window shows the dates it resolved to), the card's own filters when you ran a card, and each measure's comparison windows. When measures ran over different periods (one for the full month, one month to date), a filter that applied to some of them names them in measures. A date filter names the calendar zone the query ran in as timezone: bounds that span whole days in that zone are those dates.
• skipped: each filter it left out, with the reason: dataset_not_reachable, field_not_resolvable, missing_metadata or unsupported_calculated_filter.

It never includes security policies or their values. "responseDetail": "compact" leaves out duplicate arrays, full field source metadata and the full SQL text, and lists what it left out in omitted.

metadata.resolvedTimeWindow says which dates a timeWindow covered:

{
  "window": { "kind": "periods", "unit": "month", "from": -3, "to": -1, "anchor": "latest_data" },
  "label": "Last 3 months of data",
  "definition": "the 3 months before the month of the latest date in the data, whole months only",
  "dateField": "order_date",
  "start": "2026-01-01T00:00:00.000Z",
  "end": "2026-03-31T23:59:59.999Z",
  "timezone": "UTC",
  "latestData": "2026-04-14T00:00:00.000Z"
}

• window is the window you asked for, in the form you'd send to get the same dates again. label and definition say it in words.
• start and end are the bounds the query ran with. Their day boundaries are in timezone. They're the window's own bounds: other filters in executionResult.constraints can narrow the rows further.
• latestData is the newest row's date that a latest_data window counted back from. When no rows match the query's other filters, the window has no start or end.
• On a comparison, the window has no bounds of its own: executionResult.constraints lists the comparison windows it placed.

Period change results. A period-change call reports its window in metadata.timeWindow, with the same fields. When it finds no changes, it says why in metadata.noChanges, never just an empty list:

{
  "reason": "no_values_in_window",
  "message": "No Revenue values from 2026-10-01 to 2026-10-31 (This month).",
  "fix": "To count back from the newest row, use anchor \"latest_data\"."
}

Report noChanges.message to your user. An empty period change doesn't mean nothing changed.

When a field is wrong or missing, the tool returns isError: true with a validation payload: a code such as missing_measure or invalid_dimension, the valid candidates from the schema, and a recommended next step.

Run a dashboard card

Pass fromCard to answer from a dashboard card exactly as your users see it. The tool runs the card's own query with everything it runs on its dashboard: its fields, filters and drill steps, the dashboard's default inputs and date range, its parameters and its comparisons. The card runs as a new viewer opens the dashboard, under your security policies, and you need access to the dashboard.

{ "fromCard": { "dashboardId": "dash_abc", "cardId": "card_123" } }

The result is the card's rows (at most 1,000) with executionResult.metadata.queryApproach set to "dashboard_card_replay", and executionResult.constraints naming the filters and date windows the card applied. To ask something the card doesn't show, build the query with the arguments above instead.

See Querying Data for more examples.

semaphor_matrix

Runs a governed Matrix window: multi-level row and column hierarchies, totals and subtotals, scoped sorting, and Top or Bottom N with Others.

Returns: executionResult, with the requested window at executionResult.result.window. A page cursor asks for the next sibling window; it doesn't mean the data was cut off. A window is never a complete export, and unloaded cells aren't zeros. This tool always returns JSON.

semaphor_plan_analytics_recovery

Plans the next governed tool calls when an agent has a typed question and schema evidence but still has unanswered parts. It returns plannedToolCalls (such as semaphor_get_dataset_schema or semaphor_analyze) and diagnostics. It plans; it doesn't run queries.

SQL

semaphor_query_sql_advanced

Runs SQL against a connection, under the same security policies as every other query, with optional Python post-processing. Use it when a question can't be expressed through semaphor_analyze. Needs SQL access.

Returns: records, rowLimitExceeded, optional output and warnings, the echoed fallback reason, and executionResult.

{
  "connectionId": "conn_123",
  "analyzeFallbackReason": "unsupported_sql_construct",
  "analyzeFallbackExplanation": "Needs a running total with a window function over monthly revenue.",
  "sql": "SELECT month, revenue, SUM(revenue) OVER (ORDER BY month) AS running_total FROM monthly_revenue ORDER BY month LIMIT 100"
}

Dashboards

semaphor_list_dashboards

Lists the dashboards the caller can open in a project, most recently updated first.

To read every dashboard while people may be editing them, scan oldest change first: pass updatedSince (1970-01-01T00:00:00Z for everything) and follow nextCursor to the end. A dashboard edited during the scan moves to the end and is read again, so de-duplicate by ID. The default newest-first order, and offset, can miss a dashboard that's edited between pages.

To find deleted dashboards, run a full scan with idsOnly: true: updatedSince: "1970-01-01T00:00:00Z" and no search, tags or origin. An ID that's missing from that finished scan was deleted, or you no longer have access to it. An incremental scan (a later updatedSince) or a filtered one leaves out dashboards on purpose, so don't treat its missing IDs as deletions.

Returns: dashboards (a page of rows), total and nextCursor (null on the last page). Each row has id, title, description, projectId, tags, origin, its creator and update times, and access: who can open the dashboard, as the dashboards console shows it, with a one-line summary in access.line. For tenant callers, and for dashboards that belong to a tenant, access lists only the rules that reach that tenant. With idsOnly, the response is ids, total and nextCursor.

semaphor_get_dashboard_details

Returns one dashboard's details, or several at once.

Returns: for one dashboard, its record (title, description, project, tenant, tags, access, dates) plus the parts you asked for. For several, dashboards and notFound (IDs that don't exist or that you can't open).

With a live token, every part but summary describes the dashboard on the user's screen, unsaved edits included, and names one dashboardId.

outline takes one dashboardId. It describes the dashboard for making changes: every sheet, card and filter by ID and name, each sheet's layout, each card's query in the same fields semaphor_analyze uses, each filter's reach and its default as the dashboard loads it, which cards and filters can be changed (and why not), the dashboard's updatedAt, and access: canEdit, or canCopy when you can save a private copy instead. With fields: ["outline"] alone, the response is { id, title, outline }.

{
  "dashboardIds": ["d_q1sales", "d_pipeline"],
  "fields": ["summary", "cards"]
}

semaphor_get_dashboard_analysis_context

Returns compact grounding for a dashboard the agent already knows: its cards, filters, authored measures, dimensions and date fields, source references, and optional query inputs for semaphor_analyze. Use it before broad discovery when a question starts from a dashboard. It reads the dashboard and never runs its queries. The project comes from the dashboard, so there's no projectId.

Returns: dashboard (metadata and link), summary (counts, and missingSheetIds and missingCardIds for IDs that don't exist), filters, cards (per-card analyses with their saved filterConditions and AND and OR groups), referencedSemanticDomains, referencedDatasets, referencedFieldCandidates, referencedConnections, referencedPhysicalSources, physicalSourceLimitations, analysisHints and suggestedNextSteps. A relative window such as "This month" comes back as its relative intent, and a latest-value condition as latestValue: true, because the server resolves both on every run.

Changes

semaphor_propose_change previews a change and saves nothing. semaphor_apply_change applies a stored proposal by its proposalId, as previewed (a semantic model change only if nothing it replaces has changed since). See Making Changes for every change, its fields, the responses, retries and errors.

semaphor_propose_change

Returns: proposalId, expiresAt, risk, target, summary, changes, warnings, preview, proposedOutline (with include: ["outline"]) and next. See Proposals. With a live token, the change is sent to the user's screen and the result also has delivery: its deliveryId and what became of it (applied, not_applied or not_confirmed).

semaphor_apply_change

Returns: applied, replayed, target, created, summary and warnings. Safe to retry with the same proposalId: a retry returns the recorded result with replayed: true and never applies the change twice. See Save, Copy and Apply.

Report a Problem

semaphor_report_problem

Sends Semaphor support the agent's account of what went wrong, with the user's agreement. See Report a Problem.

Returns: reportId, the report's number to give the user, and next. A report that couldn't be sent returns report_not_sent; try again later.