Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Mode Analytics MCP Server fetch the latest results for the Weekly Revenue report"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets you browse reports, manage queries, and fetch results from Mode Analytics from any MCP-compatible AI assistant or agent.
Tool | Description |
| List all database connections in the workspace |
| List all spaces (collections) |
| List reports in a given space (archived ones hidden unless |
| Search for reports by name or description across all spaces (client-side; archived ones hidden unless |
| Get report details including its SQL queries and who wrote each one |
| List recent runs for a report (state, timestamps) |
| Fetch results from a specific or latest report run |
| Create a new report in a space, optionally with initial queries |
| Update a report's name, description, or move it to a different space |
| Archive (hide) a report — reversible |
| Restore an archived report |
| Permanently delete a report (preview first, then confirm). Off unless |
| Add a SQL query to an existing report |
| Update a query's SQL, name, or data source |
| Permanently delete a query (preview first, then confirm). Off unless |
Related MCP server: Looker MCP Server
Use a Member API key (recommended). Create your own under Workspace Settings > Personal > My API Keys and save the token and secret. Member keys respect your own Mode permissions, so the agent can only see and change what you can. If you can't create one, a Workspace admin needs to enable them under Workspace Settings > Features > API Keys > Member keys.
Mode also offers Workspace API tokens, created by admins under Workspace Settings > Privacy & Security > API. These act with admin access to the whole Workspace, so only use one if you need that — see Limitations / Safety below. (Older personal API tokens can no longer be created, but existing ones keep working.)
Both kinds of key expire after 90 days by default. When yours expires, the server reports "Authentication failed"; create a new key and update your MCP config.
The server is launched with uvx, which comes with uv. Install it with brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh.
The server runs over stdio via uvx mode-mcp. Add it to your MCP client's config; most clients use this mcpServers shape:
{
"mcpServers": {
"mode-analytics": {
"command": "uvx",
"args": ["mode-mcp"],
"env": {
"MODE_WORKSPACE": "your-workspace-name",
"MODE_API_TOKEN": "${MODE_API_TOKEN}",
"MODE_API_SECRET": "${MODE_API_SECRET}"
}
}
}
}uvx installs the package from PyPI on first run and reuses that version afterwards. To pick up new releases automatically, use "args": ["mode-mcp@latest"] instead.
The ${MODE_API_TOKEN} / ${MODE_API_SECRET} references are expanded from your shell environment by clients that support it, so no secrets land in the config file. Set them wherever you keep shell secrets, e.g. in ~/.zshrc:
export MODE_API_TOKEN="..."
export MODE_API_SECRET="..."Some clients expand ${VAR}, some use another syntax (e.g. ${env:VAR}), and some don't expand references at all; check your client's docs. If a reference isn't expanded, the server stops at startup with an error naming the variable, rather than failing later with a confusing authentication error.
Variable | Required | Description |
| Yes | Your Workspace's username, as in |
| Yes | API token (from a Member API key, ideally) |
| Yes | API secret |
| No | Set to |
| No | Set to |
| No | Comma-separated tool names to disable, e.g. |
Disabled tools are never registered, so the agent doesn't see them at all.
Default: everything except the two delete tools. The agent can browse, author, and archive, but can't permanently delete anything.
Allow deletes: add "MODE_ENABLE_DELETES": "true" to env.
Read-only: add "MODE_READ_ONLY": "true" to only allow browsing and fetching results.
Anything else: list tool names in MODE_DISABLED_TOOLS.
A misspelled tool name in MODE_DISABLED_TOOLS stops the server with an error rather than silently leaving the tool enabled.
No query execution. The server deliberately does not expose a "run this query" tool. The Mode API has no endpoint for running a single query — the only way to execute SQL is POST /reports/{token}/runs, which runs every query in the report at once. On reports with many or expensive queries, that's slow, costly, and impossible to predict from the agent's side. Instead, the server focuses on browsing, authoring, and fetching results:
Write and manage SQL queries through your agent, then run them in Mode's UI where costs and side effects are visible.
Use get_run_results to pull results from completed runs back into the conversation.
Deletes are permission-scoped, not owner-scoped. The server does not check who created a report or query; what you can delete is whatever your API token is allowed to delete in Mode. With a Member API key that's limited to your own permissions, but a Workspace API token has admin access and can delete any report or query in the Workspace. That's why the delete tools are off unless you set MODE_ENABLE_DELETES=true.
Deletes can't skip the preview. When enabled, delete_report and delete_query are always two calls:
The first call deletes nothing. It returns a preview (the report's name, whether it's already archived, and its queries with who wrote each one; or a query's name, author, and SQL) plus a short confirm_code. Mode's API doesn't say who created a report, only who wrote each query.
The delete only happens when the same tool is called again with that confirm_code. The code is a fingerprint of what the preview showed, so it can't be guessed, and if the report or query changed after the preview (renamed, SQL edited, queries added), the code no longer matches and the delete is refused.
Archive instead of delete. archive_report hides a report and unarchive_report brings it back. The delete tool tells the agent to suggest archiving first.
Credentials never touch the committed config. The ${MODE_API_TOKEN} / ${MODE_API_SECRET} references in your MCP config are expanded from your shell environment at launch (in clients that support it), so the file is safe to commit. Keep the raw secrets in env vars and don't commit them.
git clone https://github.com/nataliemona/mode_mcp.git
cd mode_mcp
uv sync --dev
uv run pytestAdd a SQL query to an existing report.
This is a write operation — it adds a new query to the report.
Args: report_token: The report to add the query to. raw_query: SQL query text. data_source_id: Data source ID (use list_data_sources to find it). name: Optional query name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| raw_query | Yes | ||
| report_token | Yes | ||
| data_source_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It discloses that this is a write operation adding a new query, but that restates the name and adds no information about permissions, validation of the SQL, reversibility, or side effects on existing queries in the report.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence, and the Args block is compact. The second line ("This is a write operation...") partially repeats the first sentence, a small redundancy in an otherwise tight description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values needn't be explained, and all four parameters get a gloss. However, with zero schema coverage and no annotations, an agent still lacks detail on parameter formats, error behavior, and any authorization requirements for this mutation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for bare titles. It does map all four parameters to their meaning and usefully points at list_data_sources for the data source ID, but gives no format or constraint detail beyond one-phrase glosses.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Add a SQL query to an existing report") and clarifies it creates a new query rather than modifying one, which implicitly separates it from the sibling update_query. It is clear and actionable, though it never names update_query or create_report explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: this is for attaching a query to an existing report. The only routing help is a pointer to list_data_sources for the data_source_id, which is parameter-level rather than tool-level. No when-not conditions or sibling comparisons are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive a report, hiding it from view. Reversible with unarchive_report.
This is the safe alternative to delete_report.
Args: report_token: The report to archive.
| Name | Required | Description | Default |
|---|---|---|---|
| report_token | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it does disclose the two traits that matter most for a mutation: the report is hidden rather than destroyed, and the operation is reversible via unarchive_report. It does not mention permission requirements, whether scheduled runs/subscriptions are affected, or idempotency, which is why it is not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Effect and reversibility are front-loaded in the first sentence, and the tool comparison follows immediately. The trailing Args block is largely redundant with the schema, which keeps it out of the top score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, and the description covers effect, reversibility, and the alternative tool. For a single-parameter reversible archive operation this is nearly sufficient; only side effects on dependent runs/schedules and permissions are unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single required parameter, so the description must compensate but instead only restates the property name ('The report to archive'). No hint about token format, where the token comes from (get_report/search_reports), or whether an invalid token errors.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource plus the concrete effect ('hiding it from view'), and explicitly positions itself against siblings unarchive_report and delete_report. An agent can distinguish this from every other report tool in the list without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear routing context: reversible with unarchive_report and framed as 'the safe alternative to delete_report', which tells the agent when to prefer it over a destructive delete. It stops short of stating the inverse condition (when archiving is unnecessary or when delete is actually required), so it is strong but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new report in a space, optionally with initial SQL queries.
This is a write operation — it creates a report visible to the workspace.
If any queries fail to add, the report is still created; inspect
queries_added and queries_failed in the result.
Args: space_token: Space to create the report in (use list_spaces to find it). name: Report name. description: Optional report description. queries: Optional list of queries to add. Each dict should have: - raw_query (str): The SQL text. - data_source_id (int): Data source ID (use list_data_sources). - name (str, optional): Query name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| queries | No | ||
| description | No | ||
| space_token | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and mostly does so: it flags the operation as a write visible to the workspace and discloses the important partial-failure semantic (report is created even if queries fail, inspect queries_added/queries_failed). It omits permission/auth requirements and any idempotency or rate-limit behavior, so it is not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The write/visibility warning and failure semantics are front-loaded before the Args block, and each parameter line is terse. Slightly verbose overall but no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with an output schema present, the description gives what the schema cannot: the write side effects, partial-failure behavior, and full parameter semantics. The remaining gap is permissions/preconditions for creating in a workspace space.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: every one of the 4 parameters is documented, including the optionality of description and queries and the internal structure of each query dict (raw_query, data_source_id, name). This meaningfully exceeds what the bare schema conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb and resource ('Create a new report in a space') and adds a scope qualifier ('optionally with initial SQL queries'). The word 'new' cleanly separates it from the sibling update_report, so an agent can route without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent how to satisfy the required inputs by pointing at siblings ('use list_spaces to find it', 'use list_data_sources'). It does not state when to prefer add_query over passing queries here, or any exclusion, so it stops short of explicit when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a report's details and its queries (SQL).
Args: report_token: The report token.
| Name | Required | Description | Default |
|---|---|---|---|
| report_token | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. "Get" implies a read-only operation and the description usefully discloses that the payload includes both report details and SQL queries, but says nothing about permissions, error behavior, or whether archived reports are retrievable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening sentence is tight and front-loaded, but the Args block duplicates the schema verbatim and consumes roughly half the text without adding information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return shape need not be described, and the tool is a simple one-parameter getter. Still, nothing is said about token provenance, access requirements, or behavior on invalid/archived tokens, leaving real gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single parameter, and the description merely restates the name ("report_token: The report token") with no format, source, or example. It adds no meaning beyond the schema's type declaration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: fetching a report's details plus its SQL queries. That scope is clear, but it never contrasts itself with siblings like search_reports or list_reports, so the agent must infer the distinction from name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance and no mention of alternatives such as search_reports for discovery or list_reports for enumeration. The only implied context is retrieving one report by token.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get results from a report run. Defaults to the latest run.
Each query's rows are truncated to max_rows_per_query by default so a
single call can't blow past the agent's context window. When a query was
truncated, the result includes truncated: true and row_count: <total>
so you know to re-call with a higher limit (or null) if you need all rows.
Args: report_token: The report token. run_token: Specific run token. If omitted, uses the latest succeeded run. max_rows_per_query: Max rows to return per query. Default 500. Pass null to fetch every row — can be very large (hundreds of MB) for dashboards with long time-series or wide cross-tabs.
| Name | Required | Description | Default |
|---|---|---|---|
| run_token | No | ||
| report_token | Yes | ||
| max_rows_per_query | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and largely meets it: it discloses the default truncation at max_rows_per_query, the presence of truncated: true and row_count in results, and warns that null can produce hundreds of MB. Permission/auth requirements and pagination beyond truncation are not covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core behavior — default to latest run, truncation, how to detect and overcome it — is front-loaded in the first two paragraphs. The Args block is somewhat redundant with the schema, but each entry still earns its place by adding semantics the schema lacks.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be enumerated, yet the description still names the key truncation fields an agent must act on. Combined with the default-run behavior and the size warning for large fetches, nothing needed to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does for run_token (specific run vs. latest succeeded) and max_rows_per_query (default 500, null to fetch everything). report_token is only glossed as 'The report token,' which adds nothing beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get results from a report run') and clarifies the default scope ('Defaults to the latest run'). It is clearly distinguishable in spirit from siblings like list_report_runs and get_report, but it never names or contrasts them explicitly, so an agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for when to omit run_token (latest succeeded run) versus supplying a specific one, and explicitly says to re-call with a higher limit or null when truncated. It does not, however, state when to prefer this over list_report_runs or get_report, so exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List database connections in the Mode workspace.
Args: limit: Max number of results to return (default 50).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It says nothing about read-only safety, permissions, rate limits, pagination, or whether the list is exhaustive, beyond the implied read-only nature of 'List'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core operation and uses a compact Args block for the single parameter. No wasted words, though the Args formatting is slightly boilerplate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity, simple schema, and available output schema, the description is nearly complete: it states what is listed and explains the limit parameter. It misses usage context and pagination behavior, but those are minor for this simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents the sole parameter 'limit' as 'Max number of results to return (default 50)', adding meaning beyond the bare integer type and default in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('database connections in the Mode workspace'), which clearly differs from sibling tools that deal with reports, spaces, or queries. An agent can identify the correct tool without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. Usage is only implied by the tool name, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent runs for a report.
Args: report_token: The report token. limit: Max number of runs to return (default 10).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| report_token | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not state whether this is read-only, whether it requires authentication, pagination behavior, or how 'recent' is defined. For a list operation with no safety hints, this leaves critical behavioral traits undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The prose line is concise, but then it includes an 'Args' section that restates the schema parameters without adding value. This padding reduces efficiency; a well-structured description would front-load purpose and only mention parameters if adding meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, return values need not be explained, but the description still omits critical context: what 'recent' means, whether results are paginated, required permissions, and how this differs from sibling tools. With no annotations and 0% schema coverage, the description is insufficient for an agent to invoke confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides only types and defaults. The description lists the two parameters with brief notes ('report token', 'Max number ... default 10'), but adds no format, constraints, or meaning beyond the parameter names. This does not compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'List recent runs for a report.' This is clear enough, but it does not differentiate from siblings like get_report or list_reports, and provides no scope details beyond 'recent'. It is adequate but vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance or alternatives are mentioned. The sibling get_run_results exists and likely retrieves details of a specific run, but the description does not explain when to use this list tool versus that one. Usage must be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List reports in a space. Archived reports are hidden unless include_archived.
Args:
space_token: Space token (use list_spaces to find it).
limit: Max number of results to return (default 50).
include_archived: Also return archived reports (each has an archived flag).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| space_token | Yes | ||
| include_archived | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses that archived reports are hidden by default, that include_archived reverses this, and that returned records carry an `archived` flag — real behavioral context the schema does not convey. It says nothing about ordering, pagination beyond limit, or permissions, so the disclosure is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The headline behavior (what is listed, and the archived-filtering rule) is front-loaded in the first two sentences, with parameter detail demoted to a compact Args block. Slight redundancy exists between the Args block and the schema, but it is short and each line adds a default or a pointer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained; the description still notes the per-record `archived` field. Combined with space scoping, the archived default, and the limit default, an agent has enough to call this correctly, though pagination behavior remains unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: all three parameters are documented with meaning, the default for limit (50), the default behavior of include_archived, and the cross-tool hint for resolving space_token. It stops short of syntax or format details, but the semantic gaps are filled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource with scope: 'List reports in a space', which distinguishes it from siblings like get_report and create_report. It does not explicitly contrast itself with search_reports, so the boundary between the two listing/search paths is left for the agent to infer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the description tells the agent to obtain space_token via list_spaces, and treats include_archived as the toggle for hidden records, which implies the natural default case. There is no explicit 'use this instead of search_reports when...' guidance or statement of prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List spaces (collections) in the Mode workspace.
Args: limit: Max number of results to return (default 50).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, yet it discloses only that results are listed and capped by a default of 50. It says nothing about pagination behavior (cursor/offset), rate limits, permission requirements, or whether ordering is stable — all relevant for a listing call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose in one sentence, followed by a compact Args block. The limit line partly duplicates the schema's own default value, so it is slightly redundant, but nothing is bloated and no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter listing tool with an output schema present, the description covers what the tool returns conceptually (spaces/collections) and how to bound the result set. Return-format detail is rightly left to the output schema, though pagination and auth context remain unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and there is one parameter, so the description must compensate. It does: 'limit: Max number of results to return (default 50)' explains the parameter's meaning and restates the default, filling the gap the bare integer schema leaves open.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (spaces), and disambiguates the noun by equating 'spaces' with 'collections' in the Mode workspace. It is immediately recognizable as a read-listing tool, though it offers nothing to distinguish it from siblings like list_reports or list_data_sources beyond the resource name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use context, no prerequisites, and no mention of alternatives among the twelve sibling tools. An agent gets no guidance on whether this is the right entry point for discovering spaces versus querying reports or data sources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for reports by name or description across all spaces.
Mode's REST API has no native report-search endpoint, so this fans out across every space and filters client-side (case-insensitive substring match on name and description). May be slow on large workspaces. Archived reports are skipped unless include_archived.
Args:
query: Search term to match against report names and descriptions.
limit: Max number of results to return (default 50).
include_archived: Also return archived reports (each has an archived flag).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| include_archived | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the fan-out implementation, case-insensitive substring matching, a performance warning (may be slow on large workspaces), and default filtering of archived reports. It omits auth/permission requirements and pagination behavior, so it is strong but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and the key caveat (fan-out, may be slow) are front-loaded before the parameter block, and each sentence carries information. The Args section is slightly redundant in structure but necessary given the empty schema descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the description covers the non-obvious implementation, performance, default filtering behavior, and every parameter. Nothing an agent needs to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and the Args block documents all three parameters, including the non-obvious details that limit defaults to 50, include_archived defaults to false, and archived results carry an `archived` flag. It adds real meaning over the bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names a specific verb (Search) plus the resource (reports) and the match fields (name or description) and the scope (all spaces), which clearly separates it from list_reports and get_report. An agent can distinguish it from every sibling without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains why the tool exists (no native search endpoint, so it fans out and filters client-side), which is genuine when-to-use context, and states the archived-reports exclusion. It stops short of naming a cheaper alternative such as list_reports for simple enumeration, so it is clear context without explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore an archived report.
Args: report_token: The report to unarchive.
| Name | Required | Description | Default |
|---|---|---|---|
| report_token | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It states the mutation but says nothing about required permissions, what happens if the report is not currently archived, reversibility, or side effects on runs/schedules — significant gaps for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose sentence is front-loaded and the whole definition is very short with no filler. The "Args:" docstring boilerplate is slightly redundant but does not bloat the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. However, as an unannotated mutation tool with an undocumented parameter and no mention of preconditions or side effects, the definition leaves an agent guessing about safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, but "report_token: The report to unarchive" merely restates the parameter name/type with no format, token source, or example. It adds no real semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Restore an archived report" gives a specific verb (restore) and resource (archived report), and the inverse relationship to the sibling archive_report is inferable from the name and wording. It is clear but never explicitly contrasts itself with archive_report, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage only through the phrase "archived report" — no explicit when-to-use, no prerequisites, and no mention of archive_report or other siblings as alternatives. An agent gets no routing guidance beyond the obvious inverse naming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a SQL query in a report.
This is a write operation — it modifies an existing query.
Args: report_token: The report containing the query. query_token: The query to update (use get_report to find query tokens). raw_query: New SQL text. Omit to leave unchanged. name: New query name. Omit to leave unchanged. data_source_id: New data source ID. Omit to leave unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| raw_query | No | ||
| query_token | Yes | ||
| report_token | Yes | ||
| data_source_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the essential mutation semantics: 'This is a write operation — it modifies an existing query,' plus partial-update behavior via 'Omit to leave unchanged.' It says nothing about required permissions, error behavior for a bad token, or whether changes are reversible/versioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose plus the write warning, followed by a scannable Args list. The opening two sentences overlap slightly (both restate that it modifies an existing query), but there is no real waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation. The description covers mutation semantics, all parameters, and a discovery path for the tokens; only permission/error context is absent, which is minor for this operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate and it does: all five parameters are explained, including the non-obvious 'omit to leave unchanged' semantics for the three optional fields, and the token-discovery pointer for query_token. This adds meaning well beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (update a SQL query inside a report) and clarifies it operates on an existing query, which implicitly distinguishes it from the sibling add_query. It does not explicitly name or contrast any sibling, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete workflow hint for the required token parameter ('use get_report to find query tokens'), routing the agent to the right sibling. It offers no when-not guidance (e.g., when to use add_query vs update_query, or what happens if the query does not exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a report's name, description, or move it to a different space.
This is a write operation — it modifies an existing report.
Args: report_token: The report to update. name: New report name. Omit to leave unchanged. description: New description. Omit to leave unchanged. space_token: Move report to this space. Omit to leave in current space.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| description | No | ||
| space_token | No | ||
| report_token | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the key traits: it is a write/mutation and each field is a partial update ('omit to leave unchanged'). However, it omits permission requirements, whether a space move is reversible or destructive, and any error/confirmation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action in the first sentence, flags the write nature second, then lists params. The Args block is slightly redundant with the opening sentence but earns its place by documenting per-parameter behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the description covers the mutation nature and all parameter semantics. The remaining gap is behavioral context such as permissions and reversibility, minor for a 4-param update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it names all four parameters and explains the semantics of each, including the optional/null 'omit to leave unchanged' behavior for name, description, and space_token.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (update) and resource (report), and enumerates the mutable fields (name, description, space). It clearly differs from create_report/get_report, though it doesn't explicitly contrast with the adjacent sibling update_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it is a write operation but gives no guidance on when to reach for this versus update_query, archive_report, or create_report. No prerequisites or selection criteria are offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1add_queryarchive_reportcreate_reportget_reportget_run_resultslist_data_sourceslist_report_runslist_reportslist_spacessearch_reportsunarchive_reportupdate_queryupdate_reportScored across 13 tools
Each tool targets a distinct resource and action: reports (create/get/update/archive/unarchive/list/search), queries (add/update), and read-only listings (spaces, data sources, runs, run results). The archive/unarchive pair and list_reports vs search_reports are clearly distinguished by scope and description, leaving no real overlap.
All 13 tools follow a strict snake_case verb_noun convention (create_report, update_query, list_spaces, get_run_results, etc.), including consistent use of the archive/unarchive antonym pair. No mixing of styles or verb conventions.
At 13 tools, the set is well-scoped for a report/query management domain, with each tool earning its place and no redundant operations. It stays comfortably within the ideal 3-15 range.
Report lifecycle is well covered (create, get, update, list, search, archive, unarchive), plus query add/update and run inspection. Minor gaps remain: there is no delete_query to remove a query from a report, and no tool to trigger a report run even though run-result and run-list tools exist.
Governed app access for AI agents: 1,000+ apps & 12,000+ tools via Code Mode MCP.
Let AI agents query data and act across all your business apps via MCP.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
