Direct your agent safely and precisely

← Agents

Tell the agent your workspace, desired outcome, and what it may change. A useful request is: “In the Analytics workspace, inspect the revenue metric and report last month’s weekly revenue. Do not change definitions.” For authoring, describe the exact change and ask the agent to report the saved resource and verification result.

Discover before acting

Call monomer_list with {"path":"workspaces"} and select a returned workspace ID. This discovery call returns workspaces with each workspace’s workspaceId, organizationId, organizationDisplayName, displayName, and sample across your current active Organization memberships. sample is {"dataset":"acme-cloud@3"} (or an earlier acme-cloud@ version) for a Workspace with Monomer’s read-only sample data about Acme Cloud, a fictional company, and null for a Workspace with your own data. It accepts only path; do not include organizationId, workspaceId, limit, or cursor. Only Workspaces you have directly joined are returned; Organization membership alone does not provide Workspace access.

If the person has no warehouse connected yet and wants to try Monomer first, there is no agent operation that sets up sample data. Ask them to choose Explore sample data on Overview in the web app, then call the discovery again and use the Workspace whose sample is not null. Identify it by that field, not by its display name, which people can change. A sample that is still being prepared is not listed yet, so call the discovery again shortly. Its data is read-only, and its shared metrics and dashboards can be read, queried, and edited like any other Workspace’s. Monomer created its starting definitions, so reads of those definitions omit updatedBy, credentialSurface, and agentApp. See Start with sample data.

Read the selected Workspace root with monomer_read:

monomer_read input

{"workspaceId":"0198ef28-2000-7000-8000-000000000001","path":"workspace"}

Follow its availableOperations to browse a collection. Call monomer_list with the explicit workspaceId, the advertised path, and required limit (an integer from 1 to 100, such as 20). There is no default page size. The same limit requirement applies to Organization resource listings with organizationId. These listings return items and may include a nextCursor. Workspace resource tools require workspaceId and omit organizationId. For example, list metrics:

monomer_list input

{
  "workspaceId": "0198ef28-2000-7000-8000-000000000001",
  "path": "workspace/metrics",
  "limit": 20
}

For Organization administration, first call monomer_list with {"path":"organizations"}. Each organizations entry contains organizationId, displayName, and your current role. Use the chosen organizationId with organization/... paths and omit workspaceId. For example, call monomer_read:

monomer_read input

{"organizationId":"0198ef28-2000-7000-8000-000000000002","path":"organization"}

Organization discovery does not grant administrative rights. The current Organization and Workspace permissions are checked on every operation. No selected Organization is stored in the connection. If names are ambiguous, confirm the intended Organization and Workspace before making changes.

Replace the illustrative IDs. Follow each returned resource’s exact path; do not build an address from its display title. Use returned cursors to continue a listing. Read the resource and its availableOperations before choosing an action. Resolve referenced metric and model names with monomer_search, then read the matching resource.

Before constructing inputs, send 1–10 entire operation entries to monomer_describe as {"operations":[...]}, with no target ID. It returns the tool name and exact input schema in compact JSON text, including contract descriptions and examples. Problem nextActions entries can be passed in the same way. Reuse a schema already fetched for the same operation in the session. Input-less actions need no schema lookup; omit input on those calls. Use monomer_check for the advertised Semantic Model or Metric check action: it saves nothing and contacts no warehouse. monomer_invoke rejects check.

MCP tools lists all tools and the describe flow; the task guides provide examples with the same tool fields.

Resource availability and actions depend on your permissions. A missing or inaccessible Organization or Workspace returns the same 404. When your role is too low, the 403 has code ROLE_REQUIRED with a sentence such as Changing a metric in Revenue Analytics needs the Editor role. Sam Kim is an Explorer. and a hint naming whom to ask. Pass both to the person you work for instead of retrying. Errors describes every status and field.

Use REST with explicit targets

With a REST-audience OAuth credential, send {"path":"organizations"} or {"path":"workspaces"} to POST /v2/agent/list for the same discovery results. Send Workspace operations to POST /v2/workspaces/{workspaceId}/agent/{operation} and Organization operations to POST /v2/agent/organizations/{organizationId}/{list|read|create|invoke}. Omit target IDs from the JSON body because the URL supplies them. The REST resource audience remains /v2/workspaces; MCP credentials use a different audience. The Agent API reference lists every operation.

Read the task guide

Call monomer_docs with {} for the documentation root. Choose a described topic and follow its published path. For example:

monomer_docs input

{"path": "/en/analyze/llms.txt"}

To read the metric-analysis guide directly, call monomer_docs:

monomer_docs input

{"path": "/en/analyze/query-metrics/index.md"}

Documentation explains the task; product tools perform it. The same guide is available in the web documentation. Keep the discovered workspace ID and product resource paths separate from these documentation paths.

Confirm the outcome

Action results give a reference in result.kind and result.path. For a saved resource, read that path and check the relevant fields; for a COLLECTION, list the path with the required limit. The response gives the current revision and next availableOperations when you need to continue. For execution, follow the run until completion and read its result. For a dashboard edit, have the person review the draft and choose Apply, or apply it when asked, then open results with Run again or Change inputs; to drop unapplied draft changes, use the draft’s advertised discard action. Keep the run or request reference when reporting a failure. If SQL validation rejects a start before acceptance, use the Problem code and retry policy to distinguish Connector repair from a Monomer service failure; Run SQL lists the causes and next steps. No run exists to poll for a rejected start.

Temporary document uploads return upload metadata and part URLs directly and have no agent read or list operation. Follow the document upload flow for that path’s completion and abort actions.

Work you do through an agent stays yours. Monomer shows it under your name with the app you connected, for example Updated by Sam Kim via Claude on a page, metric, model, dashboard, or run, and on Overview as a badge on your avatar. The name is the one the app gave when you connected it, so Monomer shows the Claude, OpenAI, or Cursor logo only when the host it verified for the app is claude.ai, chatgpt.com, or cursor.com. Any other app appears by that verified host, such as via agents.acme.dev; hover the mark to see the app’s name and host together, such as via agents.acme.dev (Acme Agent). Work recorded before Monomer kept app names reads via agent. Overview’s Agents filter lists this work.

Your agent reads the same record. A dashboard read returns updatedBy, credentialSurface (WEB or AGENT), and agentApp. A draft read returns lastEditedBy, lastEditedAt, lastEditSurface, and lastEditAgentApp, so the agent can tell you who changed a draft before you apply or discard it. Semantic model and metric reads put updatedAt, updatedBy, credentialSurface, and agentApp next to the definition body. Page reads include createdBy and updatedBy, and page versions include finalizedBy. Explore runs and dashboard query runs include credentialSurface and agentApp, and Catalog ingestions include requestedBy. A person appears as id and displayName; a page actor also carries kind (USER, AGENT, or SYSTEM) and agentApp; a Catalog ingestion’s requestedBy is always present and names the person as principalId and displayName with credentialSurface and agentApp. An app appears as clientId, name, and verifiedHost. Other provenance fields are left out when nothing was recorded. agentApp is left out for work in the app and for agent work recorded before Monomer kept app names.

Dashboard definition history records creation, Apply, and deletion with the recorded person, credential surface, and app. Read the dashboard’s advertised history path to verify those changes; the records remain available after deletion. Deleting a dashboard also removes all linked dashboard Pages, schedules, its draft, and past results, and cancels running queries. A deleted dashboard’s restorable version advertises restore, which returns the original dashboard ID and its saved definition, with future schedules; Pages and past results do not return. Read the returned dashboard to verify the restored definition. See Dashboard history, deletion, and restore for paths and permissions.

Do not blindly repeat a create request after losing the response: first inspect the collection for the resource you intended to create. For revision conflicts, read the latest draft and review other people’s changes before retrying. Task procedures live under Model, Analyze, and Dashboards.