The Redash MCP Server enables AI assistants to interact with Redash for query and dashboard management.
Key Capabilities:
Query Management: List, create, update, archive queries and view available data sources
Query Execution: Run queries and retrieve results with optional parameters
Dashboard Management: List dashboards and access details of specific dashboards/visualizations
Allows integration with Redash instances to list queries and dashboards, execute queries, create and manage queries, list data sources, and get dashboard details and visualizations
Click on "Install 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., "@Redash MCP Server show me the top 10 customers by revenue this month"
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.
Model Context Protocol (MCP) server for integrating Redash with AI assistants like Claude.
Connect to Redash instances via the Redash API
List available queries and dashboards as resources
Execute queries and retrieve results
Execute saved parameterized queries with typed values and saved defaults
Create and manage queries (create, update, archive)
Manage query parameters, dashboard parameters, and widget parameter mappings
Inspect and update dashboard widget layouts and grid positions
List data sources for query creation
Get dashboard details and visualizations
Update chart visualization options with Redash chart-specific settings
Related MCP server: redash-mcp
Node.js (v22.13 or later)
Corepack (included with Node.js 22; it selects the pnpm version pinned in package.json)
Access to a Redash instance
Redash API key
The server requires the following environment variables:
REDASH_URL: Your Redash instance URL (e.g., https://redash.example.com)
REDASH_API_KEY: Your Redash API key
Optional variables:
REDASH_TIMEOUT: Timeout for API requests in milliseconds (default: 30000)
REDASH_MAX_RESULTS: Maximum number of results to return (default: 1000)
REDASH_EXTRA_HEADERS: Extra HTTP headers to include with every Redash request. Accepts either a JSON object string or a semicolon/comma-separated list of key=value pairs.
REDASH_SOCKS_PROXY: SOCKS proxy URL for routing requests through a proxy (e.g., socks5h://localhost:1080). Use socks5h:// (with h) to delegate DNS resolution to the proxy, which is required for internal hostnames that don't resolve on the local machine.
MCP_TRANSPORT: MCP transport to use. Supported values are stdio, http, and streamable-http (default: stdio).
MCP_HTTP_HOST: Host for Streamable HTTP mode (default: 127.0.0.1).
MCP_HTTP_PORT: Port for Streamable HTTP mode (default: 3000).
MCP_HTTP_PATH: Streamable HTTP endpoint path (default: /mcp).
MCP_HTTP_ALLOWED_HOSTS: Comma-separated Host header allowlist for Streamable HTTP mode. Values are hostnames without a scheme, port, path, or wildcard.
MCP_HTTP_ALLOWED_ORIGINS: Comma-separated browser Origin hostname allowlist. Values use the same hostname-only format and also control CORS responses. Set an empty value to reject every request that includes an Origin header.
OpenTelemetry variables: optional; see OpenTelemetry observability for concrete OTLP and Prometheus configurations.
Examples:
JSON (recommended):
REDASH_EXTRA_HEADERS='{"CF-Access-Client-Id":"<client_id>","CF-Access-Client-Secret":"<client_secret>"}'Key/value list:
REDASH_EXTRA_HEADERS=CF-Access-Client-Id=<client_id>;CF-Access-Client-Secret=<client_secret>Notes:
The Authorization header is managed by the server (Key <REDASH_API_KEY>) and cannot be overridden.
All extra headers are added to every request made to Redash.
Clone this repository:
git clone https://github.com/suthio/redash-mcp.git
cd redash-mcpEnable Corepack and install dependencies:
corepack enable
pnpm installCreate a .env file with your Redash configuration:
REDASH_URL=https://your-redash-instance.com
REDASH_API_KEY=your_api_key
# Optional: Cloudflare Access (or other gateway) headers
# REDASH_EXTRA_HEADERS='{"CF-Access-Client-Id":"<client_id>","CF-Access-Client-Secret":"<client_secret>"}'Build the project:
pnpm run buildStart the server:
pnpm startThe default transport is stdio, which is the mode expected by most desktop MCP clients. The stdio entrypoint accepts both 2025-era MCP clients and clients that negotiate the current protocol.
To use this MCP server with Claude for Desktop, configure it in your Claude for Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the following configuration (edit paths as needed):
{
"mcpServers": {
"redash": {
"command": "npx",
"args": [
"-y",
"@suthio/redash-mcp"
],
"env": {
"REDASH_API_KEY": "your-api-key",
"REDASH_URL": "https://your-redash-instance.com"
}
}
}
}The server can also run as a stateless Streamable HTTP MCP server. The HTTP entrypoint is a Hono application served by @hono/node-server; environment variables configure the listener:
REDASH_URL=https://your-redash-instance.com \
REDASH_API_KEY=your_api_key \
MCP_TRANSPORT=http \
pnpm startThis starts POST http://127.0.0.1:3000/mcp by default. CLI flags override environment variables:
REDASH_URL=https://your-redash-instance.com \
REDASH_API_KEY=your_api_key \
pnpm start --transport http --host 127.0.0.1 --port 3333 --path /mcpFor a non-local bind behind an authenticated, TLS-terminating reverse proxy, explicitly configure which request hosts and browser origins may reach the server. The equivalent CLI options are --allowed-hosts and --allowed-origins.
REDASH_URL=https://redash.example.com \
REDASH_API_KEY=your_api_key \
MCP_TRANSPORT=http \
MCP_HTTP_HOST=0.0.0.0 \
MCP_HTTP_ALLOWED_HOSTS=mcp.example.com \
MCP_HTTP_ALLOWED_ORIGINS=app.example.com \
pnpm startWho uses the server | MCP URL | Allowed Host header | Allowed browser Origin |
Local MCP client |
|
|
|
Local Docker client |
|
|
|
Browser app at |
|
|
|
Host and Origin matching is case-insensitive and port-agnostic. For example, allowing app.example.com accepts the browser Origin https://app.example.com:8443. In HTTP mode, binding MCP_HTTP_HOST to a non-local address fails at startup unless both allowlist settings are explicitly present.
Host and Origin allowlists protect against DNS rebinding and unwanted browser origins; they do not authenticate MCP clients. Do not expose the server listener directly to the internet. For https://mcp.example.com/mcp, keep the listener on a private network and require authentication at the reverse proxy or gateway.
HTTP mode is stateless: the server does not issue Mcp-Session-Id, does not provide a standalone GET SSE stream, and handles each POST /mcp with a fresh MCP server instance. Both current MCP clients and 2025-era Streamable HTTP clients use that same URL. GET /mcp and DELETE /mcp return 405 Method Not Allowed.
The default bind is localhost-only (127.0.0.1) with Host and Origin protection. Browser requests from allowed origins receive CORS response headers; other origins are rejected with 403 Forbidden.
GET http://127.0.0.1:3000/healthz returns 200 OK with the body ok for lightweight health checks. It uses the same Host and Origin allowlists as the MCP endpoint and does not contact Redash. If MCP_HTTP_PATH=/healthz, that URL remains the MCP endpoint and the standalone health check is disabled with a startup warning.
The CLI handles SIGINT and SIGTERM gracefully. For example, docker stop sends SIGTERM; the server closes active MCP streams and then waits for the HTTP listener to stop before the process exits.
Operators use this integration to follow one MCP operation from the client, through this server, to Redash, and to alert on latency or process health. The CLI initializes OpenTelemetry automatically. With no exporter endpoint or exporter setting, it opens no telemetry network connection; application logs still go to stderr so stdio stdout remains reserved for MCP messages.
Choose the setup that matches the system reading the telemetry:
Who reads it | Set these variables | Where data is available |
An OpenTelemetry Collector receiving all three signals |
| Traces, metrics, and logs at the Collector OTLP/HTTP receiver |
Prometheus scraping an HTTP-mode server |
|
|
Prometheus scraping a stdio server |
|
|
A Collector plus Prometheus |
| OTLP metrics and the Prometheus endpoint |
For example, this HTTP-mode command exports all signals over OTLP/HTTP and also lets Prometheus scrape the same listener:
REDASH_URL=https://redash.example.com \
REDASH_API_KEY=your_api_key \
MCP_TRANSPORT=http \
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_METRICS_EXPORTER=otlp,prometheus \
pnpm start
curl http://127.0.0.1:3000/metricsThe server emits these signals:
Signal | Representative data | What it answers |
Traces | inbound | Which MCP or Redash operation was slow or failed? |
Metrics |
| Is latency, event-loop delay, memory, CPU, or network use changing? |
Logs | structured severity, fields, exception, and active | What happened inside the operation shown by a trace? |
The names and attributes visible in a trace backend are deliberately stable:
What the MCP client does | Span name | Attributes used to filter it |
Calls |
|
|
Reads |
|
|
Sends JSON-RPC error code | The MCP method name |
|
Posts to a custom endpoint |
|
|
mcp.protocol.version records the negotiated revision in both stdio and stateless HTTP operations. mcp.server.session.duration applies to the long-lived stdio connection; HTTP mode is stateless, so its useful lifecycle measurement is mcp.server.operation.duration. Both histograms use the MCP-recommended explicit latency buckets.
SEP-414 traceparent, tracestate, and baggage values in MCP request _meta are accepted. The extracted MCP client context becomes the MCP server span's parent, while the HTTP transport span is linked to it. Logs emitted while the tool runs carry the MCP span's trace_id and span_id.
Application log messages always go to stderr. When OTel Logs is configured, the same message is exported with its structured fields; those fields are not printed to stderr. A compatible stdio MCP client also receives the message through notifications/message for backward compatibility. Stateless HTTP does not send those notifications because each POST uses a fresh server instance; use OTel Logs or stderr there.
The OTLP exporters support gRPC, HTTP/protobuf, and HTTP/JSON:
Protocol | Variable value | Typical Collector endpoint |
OTLP/gRPC |
|
|
OTLP/HTTP protobuf |
|
|
OTLP/HTTP JSON |
|
|
Set the shared OTEL_EXPORTER_OTLP_PROTOCOL, or override it with OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, OTEL_EXPORTER_OTLP_METRICS_PROTOCOL, and OTEL_EXPORTER_OTLP_LOGS_PROTOCOL. The corresponding standard endpoint, header, certificate, compression, and timeout variables are passed to the OpenTelemetry exporters.
An endpoint enables its signal. You can make the decision explicit with OTEL_TRACES_EXPORTER=otlp, OTEL_METRICS_EXPORTER=otlp, and OTEL_LOGS_EXPORTER=otlp, or disable one with none. For example, this keeps logs on stderr while sending traces and metrics:
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.internal:4318
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=noneOTEL_SDK_DISABLED=true disables every telemetry signal. Invalid telemetry settings or an unavailable exporter produce a warning on stderr but do not stop MCP or Redash requests. Application configuration errors such as a missing REDASH_API_KEY still fail startup.
In HTTP mode, the embedded /metrics route uses the same Host allowlist as /mcp. If MCP_HTTP_PATH=/metrics, the server keeps that URL for MCP, traces it as POST /metrics, and disables the embedded Prometheus route with a warning. Set OTEL_EXPORTER_PROMETHEUS_HOST or OTEL_EXPORTER_PROMETHEUS_PORT to use a separate listener instead. A separate listener is not protected by the MCP Host/Origin checks, so bind it to 127.0.0.1 or protect it at the network layer.
Safe operation metadata is always available. Content that may contain Redash data requires an explicit opt-in:
Data | Default | With |
Tool name, query/data-source IDs, HTTP method/path/status, request header names | Recorded on the applicable span or OTel Log | Same |
Successful tool arguments and results, including SQL, description, options, visualizations, result rows, and CSV text | Omitted | Recorded once on the MCP |
Failed Redash request/response bodies and query job errors | Omitted | Recorded as structured OTel Log fields; stderr and the MCP error response remain content-free |
API keys and request header values | Never recorded | Never recorded |
The option uses the GenAI instrumentation name because the OpenTelemetry MCP conventions model a tool call as a GenAI-compatible execute_tool operation. The Redash server does not perform model inference; it reuses the common gen_ai.tool.call.* attributes so an MCP call can be correlated with the agent that invoked it. Enable the option only when the trace and log backends are approved to retain Redash content.
Initialize telemetry before importing the main package so Node HTTP and Axios are patched before Redash requests begin:
import {
initializeTelemetry,
shutdownTelemetry,
} from "@suthio/redash-mcp/telemetry";
await initializeTelemetry({ transport: "stdio" });
const { createRedashMcpServer } = await import("@suthio/redash-mcp");
const server = createRedashMcpServer();
// Connect and use the server, then flush exporters during application shutdown.
await server.close();
await shutdownTelemetry();When the embedding process exposes MCP over HTTP at POST /redash-mcp, pass that exact route during telemetry initialization and identify the application protocol when creating the server:
import {
initializeTelemetry,
shutdownTelemetry,
} from "@suthio/redash-mcp/telemetry";
await initializeTelemetry({ transport: "http", httpPath: "/redash-mcp" });
const { createRedashMcpServer } = await import("@suthio/redash-mcp");
const server = createRedashMcpServer({
networkTransport: "tcp",
networkProtocolName: "http",
recordSession: false,
});
// Connect `server` to the embedding process's POST /redash-mcp transport.
await server.close();
await shutdownTelemetry();Container images are published to GitHub Container Registry for both linux/amd64 and linux/arm64.
docker run --rm -p 127.0.0.1:3000:3000 \
-e REDASH_URL=https://your-redash-instance.com \
-e REDASH_API_KEY=your_api_key \
ghcr.io/suthio/redash-mcp:latestThe container runs Streamable HTTP internally on 0.0.0.0:3000, while the example publishes that port on the host's loopback interface only. Its default Host and Origin allowlists accept localhost access. When placing the container behind an authenticated reverse proxy or a private cluster service, set MCP_HTTP_ALLOWED_HOSTS and MCP_HTTP_ALLOWED_ORIGINS to the concrete DNS names used by clients.
Published images are signed with keyless cosign.
list_queries: List all available queries in Redash
get_query: Get details of a specific query
create_query: Create a new query in Redash
update_query: Update an existing query in Redash
get_query_parameters: Inspect saved query parameter definitions
update_query_parameters: Update saved query parameter definitions
archive_query: Archive (soft-delete) a query
list_data_sources: List all available data sources
execute_query: Execute a query and return results, with optional maxAge
execute_parameterized_query: Execute a saved parameterized query with type-aware value coercion, saved defaults, and optional maxAge
execute_adhoc_query: Execute an ad-hoc query without saving it to Redash
get_query_results_csv: Get query results in CSV format (supports optional refresh for latest data)
get_schema: Get the schema of a data source, paginated by table
Use get_schema when an MCP client needs table and column names for writing a
query. A caller can request a small page, inspect hasMore, and follow nextPage
without loading the entire warehouse schema into this MCP server. For BigQuery,
a configured location also allows the server to fetch only the requested tables.
Data source | How one page is read | Why |
BigQuery ( | Read the connection's configured | A configured location lets Redash avoid materializing its complete cached schema for very large BigQuery projects. The fallback keeps |
Query Results ( | Static schema discovery is unavailable. Use | Query Results creates its SQLite tables dynamically from saved query results, so there is no fixed table or column list for |
Other schema-capable data sources | Stream | The MCP server retains only the requested page instead of the complete Redash response. |
Parameters: dataSourceId (required), page (default 1), pageSize (default 25,
max 100), and search (optional case-insensitive substring match on table names;
pagination applies to the filtered set). The response includes hasMore and
nextPage for iterating through large schemas.
For example, to inspect tables in a BigQuery dataset named analytics_public
on data source 7, call get_schema with
{"dataSourceId":7,"pageSize":10,"search":"analytics_public."}. pageSize
limits the number of tables in one response; it does not split the columns or
nested field paths within a table. A wide table such as a GA4 event export is
therefore returned with all of its field paths even when pageSize is 1.
list_dashboards: List all available dashboards
get_dashboard: Get dashboard details and visualizations
get_dashboard_layout: Inspect widget positions, sizes, and visibility on a dashboard
get_visualization: Get details of a specific visualization
get_dashboard_parameters: Inspect dashboard parameter values and widget mappings
update_dashboard_parameters: Update dashboard parameter values and order
update_dashboard_layout: Move or resize multiple widgets in one call
update_widget_layout: Move or resize a single widget
get_widget_parameter_mappings: Inspect a widget's parameter mappings
update_widget_parameter_mappings: Update a widget's parameter mappings
create_visualization: Create a new visualization for a query
update_visualization: Update an existing visualization
update_chart_visualization: Patch chart-specific options like globalSeriesType, columnMapping, seriesOptions, legend, and axis settings
delete_visualization: Delete a visualization
Run in development mode:
pnpm run devpnpm testpnpm run e2e:testE2E tests use these default values (can be overridden with environment variables):
REDASH_URL: https://demo.redash.io
REDASH_API_KEY: test_api_key
Override example:
REDASH_URL=https://your-instance.com REDASH_API_KEY=your_key pnpm run e2e:testpnpm run inspectorv1.1.0: Added query management functionality (create, update, archive)
v1.0.0: Initial release
MIT
Subscribe to an alert to receive notifications
| Name | Required | Description | Default |
|---|---|---|---|
| alertId | Yes | ID of the alert to subscribe to | |
| destination_id | No | ID of the notification destination (optional, defaults to email) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose side effects (e.g., overwriting previous subscriptions), permissions, or return values, but it only states the obvious purpose.
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?
Single concise sentence with no fluff; front-loaded with purpose.
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 no output schema and missing behavioral details, the description fails to explain what happens after subscription (e.g., confirmation, effects on existing subscriptions).
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 100% and both parameters have descriptions; the description adds no extra meaning beyond the schema, so baseline is appropriate.
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 clearly states the tool's action (subscribe) and resource (alert), and it is distinct from sibling tools like remove_alert_subscription or mute_alert.
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 guidance on when to use this tool versus alternatives like mute_alert or remove_alert_subscription; no context on prerequisites or expected behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a dashboard to favorites
| Name | Required | Description | Default |
|---|---|---|---|
| dashboardId | Yes | ID of the dashboard to add to favorites |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. However, it only states the basic action and does not disclose behavioral traits such as whether the operation is idempotent, auth requirements, or rate limits.
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 a single sentence with no wasted words. It is front-loaded with the action. However, it could be slightly expanded with structural elements like prerequisites or 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?
Given the simplicity of the tool (1 parameter, no output schema), the description is mostly adequate but lacks behavioral context like what happens if the dashboard is already favorited or if the ID is invalid.
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 100% and includes a description for the parameter. The tool description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
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 clearly states the action (Add) and target (dashboard to favorites), distinguishing it from sibling tools like remove_dashboard_favorite and get_favorite_dashboards.
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 (when you want to add a dashboard to favorites) but provides no explicit guidance on when not to use it or alternatives. For a simple tool, this is adequate but not exemplary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a query to favorites
| Name | Required | Description | Default |
|---|---|---|---|
| queryId | Yes | ID of the query to add to favorites |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden of behavioral disclosure, but it fails to mention whether the operation is idempotent, what happens if the query is already favorited, or any authentication requirements. The description is minimal and lacks important behavioral context.
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 a single, front-loaded sentence with no extraneous information. It efficiently conveys the core purpose.
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 simple tool with one parameter and no output schema, the description is barely adequate. It does not explain what 'favorites' means, any limits, or the result of the operation. However, given the low complexity, it meets a minimum viable completeness.
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?
The input schema already provides a description for the 'queryId' parameter ('ID of the query to add to favorites'), and the description does not add further meaning. Since schema description coverage is 100%, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add a query to favorites' uses a specific verb and resource, clearly indicating the action and target. It distinguishes itself from siblings like 'remove_query_favorite' by stating the addition operation.
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 guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, such as whether the query should not already be favorited, or when to prefer other tools like 'remove_query_favorite' or 'get_favorite_queries'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive (soft-delete) a dashboard in Redash
| Name | Required | Description | Default |
|---|---|---|---|
| dashboardId | Yes | ID of the dashboard to archive |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavior. It mentions 'soft-delete' implying reversibility, but lacks details on permissions, side effects (e.g., widgets), or idempotency.
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?
Single short sentence with no fluff, front-loaded with purpose. All words are necessary.
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 simple one-parameter tool with no output schema, the description is adequate but lacks behavioral details (e.g., whether it can be undone, impact on related resources) that would help an agent execute safely.
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?
The input schema has 100% coverage with a clear parameter description. The description adds marginal context ('soft-delete') but does not significantly enhance understanding 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?
The description clearly states the action ('archive (soft-delete)') and the resource ('a dashboard in Redash'), distinguishing it from sibling tools like archive_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?
No guidance on when to use this tool vs alternatives (e.g., delete_widget, fork_dashboard) or prerequisites. The description does not mention exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive (soft-delete) a query in Redash
| Name | Required | Description | Default |
|---|---|---|---|
| queryId | Yes | ID of the query to archive |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. 'Soft-delete' implies non-permanent deletion, but lacks details on reversibility, side effects, or permissions.
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?
Single sentence, no unnecessary words. Front-loaded with the action and resource.
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 simple single-parameter tool, the description is adequate but could benefit from noting implications (e.g., if it affects associated resources). No output schema, so return info 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 coverage is 100% and the schema already documents queryId. The description adds no extra meaning beyond the schema, but meets the baseline.
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 clearly states the verb 'archive' (soft-delete) and resource 'a query in Redash'. It distinguishes from sibling tools like archive_dashboard and delete_query_snippet.
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 guidance on when to use this tool vs alternatives, no prerequisites, or conditions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new alert in Redash. Alerts notify you when a query result meets a specified condition.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the alert | |
| rearm | No | Number of seconds to wait before triggering again (null for never) | |
| options | Yes | Alert options including column to monitor, operator, and threshold value | |
| query_id | Yes | ID of the query to monitor |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It only states the basic function but lacks disclosure of side effects (e.g., whether the alert starts immediately, if subscriptions are required, or if it returns the created object).
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 two sentences with no unnecessary words. It is front-loaded with the action and explanation, though it could be more structured (e.g., list key points).
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?
No output schema and no mention of return value. Missing context about prerequisites (e.g., query must exist), optional parameters (rearm), or related tools (e.g., add_alert_subscription). For a tool with nested objects and 4 parameters, it is incomplete.
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 100% (all parameters have descriptions). The description adds little beyond the schema, merely paraphrasing 'monitor a column' as 'specified condition'. Baseline 3 is appropriate.
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 clearly states the tool creates a new alert in Redash and explains what alerts do (notify when condition met). It uses a specific verb-resource pair, distinguishing it from sibling tools like update_alert or delete_alert.
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 guidance on when to use this tool vs alternatives (e.g., add_alert_subscription, update_alert). The description does not mention prerequisites (e.g., query must exist) or any contextual conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new dashboard in Redash
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the dashboard | |
| tags | No | Tags for the dashboard |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the action. It omits details like permission requirements, idempotency, error behavior on duplicate names, or whether the created dashboard is returned.
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 a single concise sentence that front-loads the action. It is appropriately brief for a simple creation tool, but could be slightly more structured with bullet points.
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 tool's simplicity and lack of output schema, key information is missing: no mention of return value, optional tags, or any side effects. Adequate for basic use but not fully complete.
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 100% with descriptions for both parameters (name and tags). The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
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 'Create a new dashboard in Redash' clearly states the verb (create) and resource (dashboard), distinguishing it from sibling tools like archive_dashboard or update_dashboard.
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 provides no guidance on when to use this tool versus alternatives such as fork_dashboard or share_dashboard, nor any prerequisites or constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new query in Redash
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the query | |
| tags | No | Tags for the query | |
| query | Yes | SQL query text | |
| options | No | Query options | |
| schedule | No | Query schedule | |
| description | No | Description of the query | |
| data_source_id | Yes | ID of the data source to use |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It only states 'Create a new query' without disclosing side effects, required permissions, or system behavior (e.g., whether the query is saved immediately, if it triggers execution, or what happens on validation failure). The minimal description fails to inform the agent about the tool's operational characteristics.
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 extremely concise with a single sentence, containing no wasted words. However, it lacks structural elements like bullet points, examples, or breakdown of steps. The conciseness comes at the cost of informativeness, leaving it minimally adequate.
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 tool's complexity (7 parameters, no output schema, no annotations) and the presence of many sibling tools, the description is insufficient. It does not explain the return value, prerequisites (e.g., valid data_source_id), or the difference between creating a query and other query operations. The description fails to provide a complete picture for an AI agent to use the tool effectively.
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?
The input schema has 100% description coverage, providing basic meaning for all seven parameters. The description adds no additional value beyond what the schema already offers, so a baseline score of 3 is appropriate. There is no extra context about parameter relationships, constraints, or formatting.
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 clearly states the verb 'create' and the resource 'query', making the basic purpose understandable. However, it does not distinguish the tool from sibling tools like 'create_query_snippet' or 'execute_query', which could cause confusion. A more specific definition of what constitutes a 'query' in Redash (e.g., a saved SQL query) would improve clarity.
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 guidance is provided on when to use this tool versus alternatives. Sibling tools include other query creation actions (create_query_snippet) and execution tools (execute_query), but the description does not help the agent decide between them. For a CRUD tool in a domain with many similar operations, this omission is significant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new reusable query snippet
| Name | Required | Description | Default |
|---|---|---|---|
| snippet | Yes | The SQL snippet content | |
| trigger | Yes | Trigger keyword for the snippet | |
| description | No | Description of the snippet |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so description must convey behavioral traits. It only says 'create', which implies a mutation, but does not disclose side effects, permissions, or immediate availability. Minimal but not misleading.
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?
Single sentence, front-loaded, no unnecessary words. Perfectly concise.
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 simple creation tool with well-documented parameters, the description is sufficient. Lacks only minor context like return behavior or typical usage scenarios.
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 100%, so baseline is 3. Description adds no additional meaning beyond the parameter descriptions.
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?
Description clearly states 'Create a new reusable query snippet', specifying the verb and resource. It distinguishes from sibling tools like update_query_snippet and delete_query_snippet.
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 guidance on when to use this tool versus alternatives (e.g., update_query_snippet). No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new visualization for a query
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the visualization | |
| type | Yes | Type of visualization. Available types depend on your Redash instance. Use get_query to see existing visualization types in use. | |
| options | Yes | Visualization-specific configuration. The structure depends on your Redash instance and visualization type. Use get_visualization to examine existing visualizations of the same type as a reference. | |
| query_id | Yes | ID of the query to create visualization for | |
| description | No | Description of the visualization |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It merely states 'Create a new visualization' without disclosing side effects, permission requirements, idempotency, or what happens to the underlying query. This is insufficient for a mutation tool.
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 a single sentence of 7 words, which is very concise. However, it could benefit from additional structure or information without becoming verbose. Score reflects efficiency but also minimal utility.
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?
Despite having 5 parameters, nested objects, and no output schema, the description is extremely brief. It does not explain the concept of a visualization, what is returned after creation, or how it relates to other tools (e.g., get_visualization). The description is inadequate for the tool's complexity.
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 100%, and the schema itself provides detailed parameter descriptions (e.g., how to determine available types and options configurations). The tool description adds no parameter information, so baseline 3 is appropriate.
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 clearly states the verb 'Create' and the resource 'visualization for a query', distinguishing it from sibling tools like create_query, create_dashboard, and update_visualization. It is specific and unambiguous.
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 provides no guidance on when to use this tool versus alternatives such as update_visualization or delete_visualization. No prerequisites, context, or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new widget on a dashboard
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Text content for text widgets | |
| width | Yes | Width of the widget (1-6) | |
| options | No | Widget options | |
| position | No | ||
| dashboard_id | Yes | ID of the dashboard to add the widget to | |
| visualization_id | No | ID of the visualization to display (optional if text widget) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose behavioral traits such as required permissions, side effects, or return value. The minimal statement does not add transparency beyond the obvious.
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 a single concise sentence without superfluous content, front-loading the core purpose effectively.
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?
With 6 parameters, nested objects (position, options), and no output schema, the description is too minimal. It fails to explain widget types, the role of visualization_id, or how it relates to dashboard layout.
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 high (83%), so the schema already documents parameters adequately. The description adds no extra meaning beyond what the schema provides.
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 clearly states the action ('Create') and the resource ('new widget on a dashboard'). It is specific and distinct from sibling tools like delete_widget or update_widget.
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 does not provide when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. The context is implied but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an alert from Redash
| Name | Required | Description | Default |
|---|---|---|---|
| alertId | Yes | ID of the alert to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only says 'delete,' implying destruction, but does not mention irreversibility, cascading effects (e.g., on subscriptions), or required permissions.
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 a single, concise sentence with no wasted words. It is front-loaded and immediately clear.
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 simple 1-parameter delete tool without output schema, the description is minimally adequate but lacks details like return value, success criteria, or side effects. The absence of annotations increases the need for contextual completeness.
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 100% and the schema already describes 'alertId' as the ID of the alert to delete. The description adds no additional meaning beyond the schema, so baseline 3 applies.
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 clearly states the action ('Delete') and the resource ('an alert from Redash'), which is distinct from sibling tools like 'create_alert', 'update_alert', 'mute_alert', and 'get_alert'.
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 guidance on when to use this tool, prerequisites (e.g., alert must exist), or alternatives. The description only states what it does without context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a query snippet
| Name | Required | Description | Default |
|---|---|---|---|
| snippetId | Yes | ID of the snippet to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits such as irreversibility or permission requirements. It only says 'delete', which implies destruction but does not confirm permanence or side effects.
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 a single, short sentence that is front-loaded and contains no fluff. However, it is overly minimal and could benefit from a bit more context without being verbose.
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 simple delete operation with one parameter, the description is minimally complete. However, it lacks details on return values, error scenarios, or prerequisites that would aid an agent in execution.
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?
The input schema provides 100% coverage for the single parameter 'snippetId' with a description. The tool description adds no additional meaning beyond what the schema already specifies.
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 clearly states the action 'delete' and the resource 'query snippet', making the purpose unambiguous. However, it does not differentiate from similar sibling tools like 'archive_query' or 'delete_alert' but that is not necessary given the distinct resource type.
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 guidance is provided on when to use this tool versus alternatives (e.g., archiving vs deleting). The description simply states the action without context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a visualization
| Name | Required | Description | Default |
|---|---|---|---|
| visualizationId | Yes | ID of the visualization to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description does not disclose that deletion is irreversible and may have cascading effects. This is critical for a delete 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 description is a single sentence with no unnecessary words. It is appropriately concise for a simple operation.
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 an irreversible action with one parameter, the description is too brief. It lacks information about irreversibility, confirmation steps, or side effects, making it incomplete.
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?
The input schema has 100% coverage with a clear description for the single parameter. The tool description adds no additional meaning beyond the schema, so baseline score of 3 applies.
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 clearly states the verb 'Delete' and the resource 'visualization', differentiating it from sibling tools like create_visualization, update_visualization, and get_visualization.
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 guidance on when to use this tool versus alternatives (e.g., archive or deactivate). The description does not specify prerequisites or conditions for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a widget from a dashboard
| Name | Required | Description | Default |
|---|---|---|---|
| widgetId | Yes | ID of the widget to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states 'delete' without mentioning side effects (e.g., permanent removal, cascade effects), authentication needs, or confirmation steps.
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 a single, concise sentence with no redundant information. It is efficiently front-loaded.
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?
The description lacks information about return behavior, error conditions, or whether the deletion is reversible. For a destructive tool without output schema, this is insufficient for an agent to understand the full effect.
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?
The single parameter widgetId is fully described in the input schema (ID of the widget to delete). The description adds no further semantic context beyond what the schema provides.
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 clearly states the action 'Delete' and the resource 'widget from a dashboard'. It is specific enough to distinguish from delete_alert and delete_query_snippet, but does not differentiate from delete_visualization, which might be related.
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 guidance is provided on when to use this tool versus alternatives like delete_visualization or update_widget. There is no mention of prerequisites, permissions, or conditions for safe use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute an ad-hoc query without saving it to Redash. Creates a temporary query that is automatically deleted after execution.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | SQL query to execute | |
| dataSourceId | Yes | ID of the data source to query against |
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 discloses the temporary and auto-deletion behavior, but omits details like whether the tool can run destructive SQL, required permissions, or error handling. The disclosure is adequate but not rich.
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 two sentences, no wasted words, and front-loads the core purpose. It is perfectly concise for the information it conveys.
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 tool's simplicity and lack of output schema, the description lacks details about the return value (e.g., query results format). It is sufficient to differentiate from siblings but misses potentially useful information 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?
The input schema has 100% coverage with descriptions for both parameters (query and dataSourceId). The description does not add further meaning beyond what the schema already provides, so it meets the baseline.
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 clearly states it executes an ad-hoc query without saving, and explicitly mentions it creates a temporary query that is automatically deleted. This distinguishes it from sibling tools like execute_query which likely saves the 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 tells when to use this tool (for ad-hoc queries without persisting), but does not explicitly state when not to use or mention alternatives like execute_query for saved queries. The context is clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a saved parameterized query using its saved parameter definitions and defaults
| Name | Required | Description | Default |
|---|---|---|---|
| maxAge | No | Cache age in seconds. Use 0 to force a fresh execution. | |
| queryId | Yes | ID of the query to execute | |
| parameters | No | Explicit parameter values to coerce using the saved Redash parameter definitions | |
| useSavedDefaults | No | Apply saved default parameter values when a parameter is omitted |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only mentions execution with saved definitions and defaults, omitting details about return format, error handling, caching behavior (maxAge), or side effects. This is insufficient for a tool with 4 parameters.
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 a single, well-structured sentence without unnecessary words. However, it could include more context without verbosity, so it earns a 4 rather than 5.
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?
With 4 parameters, no output schema, and no annotations, the description lacks essential context such as return format, error behavior, and how the parameters object interacts with saved definitions. This is insufficient for an execution 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 coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema descriptions (e.g., that maxAge controls caching, parameters override defaults, or useSavedDefaults applies omitted values).
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 clearly identifies the tool's action ('Execute'), the resource ('saved parameterized query'), and the specific behavior ('using its saved parameter definitions and defaults'). This effectively distinguishes it from sibling tools like execute_adhoc_query and execute_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 implies usage when a saved parameterized query exists, but it does not explicitly state when to use this tool over similar siblings (e.g., execute_query) or provide any prerequisites, when-not-to-use conditions, or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a Redash query and return results
| Name | Required | Description | Default |
|---|---|---|---|
| maxAge | No | Cache age in seconds. Use 0 to force a fresh execution. | |
| queryId | Yes | ID of the query to execute | |
| parameters | No | Parameters to pass to the query (if any) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It only states 'execute' and 'return results', omitting behavioral traits such as whether the query is cached by default, authentication needs, or potential side effects. The maxAge parameter hints at caching, but the description does not elaborate.
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 extremely short (one sentence), but it is under-specified. Conciseness should not come at the expense of completeness; here the brevity omits critical information, making it less useful.
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 absence of an output schema and the existence of several sibling tools with similar purposes, the description is incomplete. It does not describe return formats, error behavior, or differentiate from other query execution tools.
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 100% as all three parameters have descriptions in the input schema. The description adds no additional meaning beyond what the schema already provides, warranting a baseline score of 3.
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 'Execute a Redash query and return results' clearly identifies the verb (execute) and resource (query), but it does not distinguish this tool from siblings like 'execute_adhoc_query' or 'execute_parameterized_query', which have similar purposes.
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 provides no guidance on when to use this tool versus alternatives. It lacks any context about prerequisites, preferred scenarios, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fork (duplicate) an existing dashboard
| Name | Required | Description | Default |
|---|---|---|---|
| dashboardId | Yes | ID of the dashboard to fork |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It only says 'duplicate' without explaining behavioral traits such as whether it's a deep copy, what happens to the original, permissions needed, or response details. This is insufficient for a mutation tool.
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 a single, efficient sentence. While it could include more detail without becoming verbose, it is not overly terse and gets the main point across. However, it is not front-loaded with critical distinguishing info.
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 tool has a simple input and no output schema, the description fails to specify what the tool returns (e.g., new dashboard ID) or whether the fork includes widgets/layout. This incompleteness could cause incorrect usage.
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 100%, and the parameter 'dashboardId' is described in the schema as 'ID of the dashboard to fork'. The description adds no extra meaning beyond this, so it meets the baseline but does not enhance understanding.
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 explicitly states the action (fork/duplicate) and the resource (dashboard). It distinguishes from 'create_dashboard' (new from scratch) and 'archive_dashboard' (delete) by specifying duplication of an existing dashboard.
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 guidance is provided on when to use this tool versus alternatives like 'create_dashboard' or 'fork_query'. There are no prerequisites or when-not-to-use indications, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fork (duplicate) an existing query
| Name | Required | Description | Default |
|---|---|---|---|
| queryId | Yes | ID of the query to fork |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description must cover behavioral traits. Only states 'Fork (duplicate) an existing query' without explaining what duplication entails (e.g., copying visualizations, permissions, dependencies).
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?
Single sentence with parenthetical clarification. No unnecessary verbiage; front-loaded action.
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?
No output schema, no annotations, and sparse description. Lacks details on side effects, required permissions, or behavior on failure.
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 already provides 'ID of the query to fork'. Tool description does not add new semantic meaning beyond schema; baseline 3 is appropriate.
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?
Answering specifically verb+resource: 'Fork (duplicate)' clearly indicates the action, and 'an existing query' specifies the resource. This distinguishes from siblings like 'create_query' (new query) and 'fork_dashboard' (different resource).
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 guidance on when to use this tool versus alternatives like 'create_query' or 'execute_query'. Does not mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific alert
| Name | Required | Description | Default |
|---|---|---|---|
| alertId | Yes | ID of the alert to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must imply safety. 'Get' suggests a read-only operation, but does not explicitly state no side effects, idempotency, or permissions needed. Adequate but minimal.
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 a single, concise sentence with no extraneous information. However, it could be slightly more informative without sacrificing conciseness.
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 simple get operation with one parameter and no output schema, the description is minimally complete. It does not list return fields or structure, but the tool's purpose is clear.
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 100% and the parameter description already explains 'alertId'. The description adds no additional semantics beyond 'specific alert', which repeats the tool name. Baseline score applies.
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 verb 'get' and resource 'alert' are clear. The description distinguishes from 'list_alerts' by specifying 'a specific alert', but does not explicitly differentiate from other sibling tools. A higher score would require explicit mention of scope or uniqueness.
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 guidance on when to use this tool versus alternatives like 'list_alerts'. The agent must infer usage from the parameter. There are no when-not-to or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all subscriptions for an alert
| Name | Required | Description | Default |
|---|---|---|---|
| alertId | Yes | ID of the alert |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states what the tool does but does not confirm read-only behavior, potential side effects, or any restrictions. For a retrieval operation, this is a minor gap but still insufficient.
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 a single focused sentence with no unnecessary words, directly conveying the tool's purpose.
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?
The description is sufficient for a simple retrieval tool with one parameter, but it lacks any mention of the return format or behavior, which would be helpful given no output schema.
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 100% and the description implies the parameter role, but it adds no new meaning beyond the schema's description 'ID of the alert'. Baseline score due to high coverage.
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 'Get all subscriptions for an alert' clearly states the action and resource, differentiating it from sibling tools like add_alert_subscription and remove_alert_subscription.
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 usage guidelines are provided. While the tool's purpose is straightforward, there is no guidance on when to use this vs. other subscription-related tools, such as add_alert_subscription or remove_alert_subscription.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific dashboard
| Name | Required | Description | Default |
|---|---|---|---|
| dashboardId | Yes | ID of the dashboard to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'get details', with no mention of read-only nature, permissions, response format, or pagination. For a read operation, minimal behavioral context is given.
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 a single sentence of 6 words, very concise. No extraneous information. However, it could be slightly more descriptive without harming conciseness.
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 simple tool with one parameter and no output schema, the description adequately states the purpose. However, without describing the return value, an agent may not know what to expect. Additional context like 'returns dashboard object with all fields' would improve completeness.
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 100%, with dashboardId described as 'ID of the dashboard to get'. The description adds no new meaning beyond the schema. Baseline 3 applies.
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 clearly states the action (Get) and resource (dashboard details). It distinguishes from siblings like list_dashboards (list all) and get_dashboard_by_slug (alternative lookup) by indicating it retrieves a specific dashboard via ID. However, it could be more specific about what 'details' includes.
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 guidance on when to use this tool versus alternatives like get_dashboard_by_slug or list_dashboards. The intended use case (when you have a dashboard ID) is only implied by the parameter, not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific dashboard by its slug
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Slug of the dashboard to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, authorization requirements, or side effects. The description carries the full burden for transparency but fails to deliver.
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?
A single, clear sentence with no superfluous words. Efficiently conveys the basic purpose.
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 simple retrieval tool, the description is minimal but lacks critical details such as what 'details' includes, and there is no output schema to compensate. Without annotations, the safety profile is absent.
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?
Input schema has 100% coverage with one parameter ('slug') already described. The description adds no new meaning beyond noting the parameter in the phrase 'by its slug', which is redundant.
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 clearly states the action (get details) and the resource (a specific dashboard), and specifies the identifier (slug), which differentiates it from sibling tools like get_dashboard (likely by ID) and get_public_dashboard.
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 guidance is provided on when to use this tool versus alternatives like get_dashboard (by ID) or list_dashboards. It implies usage when a slug is known but lacks explicit context or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current widget layout for a dashboard
| Name | Required | Description | Default |
|---|---|---|---|
| dashboardId | Yes | ID of the dashboard |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden of disclosing behavior. It only states it's a 'get' operation but does not mention any specifics like auth requirements, rate limits, or what 'layout' entails (e.g., positions, sizing).
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 a single, efficient sentence of 8 words that directly states the purpose. It is front-loaded and contains no unnecessary 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?
Given the tool has only one parameter and no output schema, the description is minimally adequate. However, it does not explain what the return value or layout structure contains, which could be critical for agent selection.
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?
With 100% schema description coverage, the schema already documents the dashboardId parameter. The description adds no additional meaning, format, or constraints beyond what the schema provides, so a baseline score of 3 is appropriate.
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 clearly states the verb 'Get' and the specific resource 'current widget layout for a dashboard', which distinguishes it from sibling tools like get_dashboard (gets dashboard metadata) or get_widget (gets a single widget).
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 provides no guidance on when to use this tool versus alternatives such as get_dashboard or list_widgets. It lacks any context about prerequisites or appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current dashboard parameter values and widget mappings
| Name | Required | Description | Default |
|---|---|---|---|
| dashboardId | Yes | ID of the dashboard |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears the full burden. It indicates a read operation, implying no destructive side effects, but does not mention authorization needs, rate limits, or what happens if the dashboard does not exist. For a simple getter, this is adequate but minimal.
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 extremely concise, consisting of a single phrase that efficiently conveys the tool's purpose. No redundant words or sentences are present.
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 tool's simplicity (single parameter, no nested objects, no output schema), the description covers the essential functionality: it returns 'current dashboard parameter values and widget mappings'. This is sufficient for an agent to understand the tool's role, though more detail on the output structure would strengthen completeness.
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?
The input schema provides 100% coverage with a clear description for the sole parameter 'dashboardId' ('ID of the dashboard'). The tool description adds no further semantics beyond the schema, so a baseline of 3 is appropriate.
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 clearly specifies the tool's function: retrieving current dashboard parameter values and widget mappings. It uses a specific verb ('Get') and resource ('dashboard parameter values and widget mappings'), distinguishing it from sibling tools like 'get_dashboard' or 'get_widget_parameter_mappings'.
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 for accessing current parameter values and mappings, but lacks explicit guidance on when to prefer this tool over alternatives such as 'get_widget_parameter_mappings' or 'get_dashboard'. No when-not-to-use or prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all tags used in dashboards
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose that the tool is read-only (get all tags). It does not explicitly state behavioral traits like idempotency or side-effect-freeness, but the verb 'get' implies a safe operation. Minimal for a simple tool.
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?
A single, clear sentence with no extraneous words. It is appropriately front-loaded and every word earns its place.
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 no parameters and no output schema, the description is complete enough for a simple list retrieval. It could optionally mention the data structure of tags, but it is not required.
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?
The input schema has zero parameters, so the description does not need to add parameter meaning. It correctly describes the action without needing to compensate for parameter details.
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 'Get all tags used in dashboards' clearly states the action (get), the resource (tags), and the scope (used in dashboards). It effectively distinguishes from sibling tools like get_query_tags.
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 for retrieving dashboard tags but offers no explicit guidance on when to use this tool versus alternatives like get_query_tags or list_dashboards. It lacks when-not or exclusionary context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get dashboards marked as favorite by the current user
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (starts at 1) | |
| pageSize | No | Number of results per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits like read-only nature, pagination, or authentication. It only says 'get dashboards' but does not clarify if it's read-only or if there are any side effects.
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?
Single sentence, front-loaded, no unnecessary words. Maximally concise.
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?
No output schema and description omits return format or constraints on pagination. For a simple list tool it is adequate but could include more context about expected results.
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 100% and schema descriptions already explain page and pageSize defaults. The tool description adds no new parameter information, warranting baseline 3.
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 clearly states the verb 'get', the resource 'dashboards', and the filter 'marked as favorite by the current user'. This distinguishes it from sibling tools like list_dashboards or get_my_dashboards.
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 guidance is provided on when to use this tool versus alternatives. It does not mention when not to use it or suggest other tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get queries marked as favorite by the current user
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (starts at 1) | |
| pageSize | No | Number of results per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It accurately implies a read-only operation but does not disclose pagination behavior, rate limits, or authentication requirements. The core behavior is clear but lacks depth.
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?
A single, concise sentence that efficiently conveys the purpose. It is front-loaded and contains no filler, though it could include a brief note on pagination without sacrificing brevity.
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?
The tool is simple with only two optional parameters and no output schema. The description covers the core purpose but does not mention that results are paginated or what the response format is. It is adequate but not fully complete.
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 100% with descriptions for page and pageSize. The description adds no additional meaning beyond what the schema already provides, so it meets the baseline but does not exceed it.
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 explicitly states 'get queries marked as favorite by the current user' with a specific verb and resource, and it clearly distinguishes from sibling tools like get_my_queries (all queries) and add_query_favorite (action to mark).
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 guidance is provided on when to use this tool versus alternatives such as get_my_queries or list_queries. There is no mention of context like filtering or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get dashboards created by the current user
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (starts at 1) | |
| pageSize | No | Number of results per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the filter but does not disclose pagination behavior, rate limits, authorization details, or return format beyond what the schema implies.
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 a single, front-loaded sentence with no unnecessary words. It efficiently communicates the core purpose.
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 (two optional pagination params, no output schema), the description is largely complete. It covers the essential purpose, though it could mention that results are paginated or the expected response structure.
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 100% with clear parameter descriptions for page and pageSize. The tool description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
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 clearly states the verb 'Get' and resource 'dashboards' with a specific filter 'created by the current user'. This distinguishes it from siblings like 'get_dashboard' (single) and 'list_dashboards' (all).
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 for retrieving the user's own dashboards but does not explicitly state when to use this tool versus alternatives like 'list_dashboards' or 'get_favorite_dashboards'. No guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get queries created by the current user
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (starts at 1) | |
| pageSize | No | Number of results per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It correctly indicates the filtering by current user but does not disclose pagination behavior, sorting, or authentication requirements. Adequate for a simple read 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?
Single sentence, no extraneous words. Efficiently communicates the core functionality.
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 simple list tool with two parameters fully described in schema, the description is adequate. Lacks details about return format or sorting, but not critical given tool simplicity.
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?
Input schema covers both parameters (page, pageSize) with descriptions, so schema coverage is 100%. Description does not add additional meaning beyond what schema already provides.
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 clearly states the action (get), resource (queries), and scope (created by current user). It distinguishes from sibling tools like list_queries, get_recent_queries, and get_favorite_queries.
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 explicit when-to-use or when-not-to-use guidance. Usage is implied: to retrieve only the current user's queries. Does not mention alternatives or exclusion of other tools like list_queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a public dashboard by its share token
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Public share token of the dashboard |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure burden, but it only states the action. It does not mention read-only nature, authentication requirements, rate limits, or idempotency, leaving important traits unspecified.
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 a single, focused sentence with no extraneous words. It is appropriately sized for a simple tool.
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?
The description omits what the tool returns (e.g., full dashboard object). Since there is no output schema, the description should clarify the return value to ensure the agent understands the outcome.
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?
The schema provides 100% coverage for the single parameter (token) with a description. The tool description adds no additional meaning beyond what the schema already offers, so baseline score of 3 is appropriate.
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 clearly states the tool retrieves a public dashboard using a share token, but does not differentiate it from similar tools like get_dashboard or get_dashboard_by_slug. The name implies public access, but explicit contrast is missing.
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 guidance is provided on when to use this tool versus alternatives such as get_dashboard (for private dashboards) or get_dashboard_by_slug. The agent receives no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific query
| Name | Required | Description | Default |
|---|---|---|---|
| queryId | Yes | ID of the query to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden for behavioral disclosure. It only states 'Get details', which hints at read-only but does not specify permissions, rate limits, or what 'details' includes. This is minimal transparency.
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 a single concise sentence with no waste. It is front-loaded and efficient, though adding minor behavioral context could improve it without losing conciseness.
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 simple read tool with one parameter and no output schema, the description is minimally adequate. It tells the agent what it does but lacks details on output format, prerequisites, or any side effects, leaving gaps.
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 100%, and the schema already describes 'queryId' as 'ID of the query to get'. The description adds no extra meaning beyond what the schema provides, so baseline score of 3 is appropriate.
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 clearly states the action 'Get' and the resource 'details of a specific query', which is distinct from sibling tools like 'list_queries' (collective) or 'create_query' (creation).
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 when you have a queryId and need its details, providing clear context. However, it does not explicitly state when not to use it (e.g., to list queries) or mention alternatives, but the context is sufficient for differentiation from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the saved parameter definitions for a query
| Name | Required | Description | Default |
|---|---|---|---|
| queryId | Yes | ID of the query |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It implies a read-only operation with 'get', but does not disclose permissions, whether defaults are included, or any other behavioral details. It is adequate but minimal.
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 a single concise sentence with no wasted words. It could be slightly more informative but is appropriately sized for a simple tool.
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?
The description does not explain what the returned parameter definitions contain (e.g., name, type, default value). Without an output schema, the agent is left guessing about the structure, making it incomplete.
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 100%, already describing 'queryId' as 'ID of the query'. The descriptive text adds no further semantics (e.g., how to obtain the ID, constraints). Baseline of 3 applies as schema does the heavy lifting.
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 clearly states the verb 'Get' and the resource 'saved parameter definitions for a query', which is specific and distinguishes it from siblings like 'get_query' and 'update_query_parameters'.
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 explicit guidance on when to use this tool or when not to use it. The context implies it's for retrieving parameter definitions, but no alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get query results in CSV format. Returns the last cached results, or optionally refreshes the query first to get the latest data. Note: Does not support parameterized queries.
| Name | Required | Description | Default |
|---|---|---|---|
| queryId | Yes | ID of the query to get results from | |
| refresh | No | Whether to refresh the query before fetching results to ensure latest data (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses caching behavior and refresh option; no annotations provided so description carries full burden. Could mention if CSV is returned inline or as download, but still transparent.
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?
Three sentences with no filler. Front-loaded with main action, efficiently provides key behavioral details.
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?
Adequate for a simple read tool with two parameters. No output schema, so format of CSV response is assumed. Could mention delivery mechanism, but overall complete for selection and 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 has 100% description coverage, but the description adds value by explaining the refresh parameter's effect (cached vs fresh) and the restriction on parameterized queries, which is not in 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?
The description clearly states the tool retrieves query results in CSV format, distinguishes itself from siblings like get_query (JSON) and execute_query (non-cached) by noting caching and refresh behavior, and explicitly states lack of parameterized query support.
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?
Provides explicit guidance on when to use refresh (true for latest data, false for cached) and explicitly notes unsupported parameterized queries, directing users to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific query snippet
| Name | Required | Description | Default |
|---|---|---|---|
| snippetId | Yes | ID of the snippet to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It states 'get', implying a read-only operation, but does not disclose potential side effects, auth requirements, or return format. Minimal but adequate for a simple get.
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?
Single sentence, no redundant information. Every word serves a purpose. Highly efficient for a simple get tool.
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 no output schema, the description could hint at what 'details' includes (e.g., fields like content, name). However, for a simple get with one parameter, it is minimally complete. A 3 reflects adequate but not thorough coverage.
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 100% with a clear description for snippetId. The tool description adds no additional meaning beyond what the schema already provides (e.g., 'ID of the snippet to get' mirrors the parameter description). Baseline 3 as per rubric.
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 clearly states the verb 'get' and the resource 'details of a specific query snippet', distinguishing it from sibling tools like list_query_snippets (list) and create_query_snippet (create).
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 explicit guidance on when to use this tool versus others (e.g., list_query_snippets). The context of needing a snippetId is implied but not elaborated. No alternatives or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all tags used in queries
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility. It only states it 'gets' tags, implying read-only, but does not disclose scope, authorization needs, side effects, or output format. Minimal behavioral disclosure.
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?
Extremely concise with one sentence containing no wasted words. Every word carries meaning. Appropriate length for a simple tool with no parameters.
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 no parameters, no output schema, and no annotations, the description is minimal. It tells what it does but not the format or scope of tags returned. Adequate but leaves gaps for an agent to infer behavior.
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?
The tool has zero parameters, and schema description coverage is 100%. Per guidelines, baseline is 4. The description adds no param details but none are needed. However, it could hint at output structure.
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 clearly states the action 'Get' and resource 'all tags' with context 'used in queries', which distinguishes it from sibling tools like get_dashboard_tags. It is specific and unambiguous.
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 guidance on when to use this tool versus alternatives such as get_dashboard_tags or list_queries. No context, prerequisites, or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recently accessed queries
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (starts at 1) | |
| pageSize | No | Number of results per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states the action and resource, omitting key behavioral details such as auth requirements, read-only nature, pagination behavior (despite schema parameters), or what data is returned (e.g., query metadata vs. content).
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 a single, clear sentence with no wasted words. While minimal, it efficiently communicates the core purpose. Slightly more context (e.g., scope of 'recently accessed') could be added without harming conciseness.
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 no output schema and no annotations, the description is incomplete. It fails to explain what 'recently accessed' means (e.g., time window, user-specific vs. collaborative), how pagination works, or what the response contains. A more complete description is warranted for a tool with these parameters and siblings.
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 100% for the two parameters (page and pageSize). The description adds no additional meaning beyond what the schema already provides, meeting the baseline for this dimension.
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 clearly states the tool retrieves recently accessed queries, distinguishing it from siblings like list_queries (all queries) and get_my_queries (user's own queries). However, it does not specify what constitutes 'recently accessed' (timeframe or user scope), leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool over alternatives (e.g., get_my_queries or list_queries) nor any prerequisites or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get schema of a specific data source
| Name | Required | Description | Default |
|---|---|---|---|
| dataSourceId | Yes | ID of the data source to get schema |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It only states that the tool retrieves schema (a read operation) but provides no details on response format, required permissions, or side effects. This is insufficient for a tool with no annotation support.
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 a single, concise sentence that conveys the core purpose without redundancy. It is front-loaded but could benefit from slightly more detail without sacrificing brevity.
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 tool's simplicity (1 param, no output schema, no annotations), the description is too minimal. It does not explain what the schema output contains, which is critical for an agent to interpret the result correctly.
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?
The single parameter 'dataSourceId' is fully described in the input schema (100% coverage). The description adds no additional meaning beyond mapping the parameter to 'specific data source'. Since schema coverage is high, a baseline of 3 is appropriate.
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 clearly states the action ('Get') and the resource ('schema of a specific data source'), which distinguishes it from sibling tools like get_dashboard or list_data_sources. However, it does not elaborate on what the schema entails (e.g., tables, columns), leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool, when not to use it, or alternatives. The description does not differentiate its use case from related tools like list_data_sources or get_query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific visualization
| Name | Required | Description | Default |
|---|---|---|---|
| visualizationId | Yes | ID of the visualization to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should fully disclose behavior. It only states 'get details' without specifying what details entail, no mention of read-only nature, error responses, or authentication needs. This is insufficient.
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 very concise, using only one sentence. However, it sacrifices necessary detail for brevity, so not a perfect 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?
For a simple retrieval tool with one parameter and no output schema, the description is too minimal. It lacks any behavioral context, error handling, or response structure, which are needed given the number of sibling tools.
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 100%, and the description adds no new meaning beyond the schema. The schema already describes visualizationId as 'ID of the visualization to get'. Baseline 3 applies.
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 clearly states the verb 'Get' and the resource 'visualization', and it distinguishes from sibling tools like get_dashboard or get_query. It is specific and unambiguous.
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 guidance on when to use this tool versus alternatives. Sibling tools include other get_* tools, but the description does not explain when to choose get_visualization over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific widget
| Name | Required | Description | Default |
|---|---|---|---|
| widgetId | Yes | ID of the widget to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present. The description only states 'get details', which implies a read-only operation, but it does not disclose any behavioral traits like authentication requirements, error handling, or rate limits.
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 a single concise sentence with no superfluous words. It is appropriately sized for a simple getter tool.
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?
No output schema is provided, yet the description does not explain what 'details' are returned (e.g., widget name, type, configuration). Missing information about error handling when widgetId is invalid or not found.
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 100% (the only parameter 'widgetId' is described as 'ID of the widget to get'). The description adds no further meaning beyond the schema, so baseline 3 applies.
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 'Get details of a specific widget' clearly identifies the action (get) and resource (widget). It distinguishes from sibling tools like 'list_widgets' (list) and 'delete_widget' (delete). However, it does not explicitly differentiate from other 'get' tools, relying on the widgetId parameter.
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 guidance is provided on when to use this tool versus alternatives, such as 'list_widgets' for browsing or other getters. The usage is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the parameter mappings for a widget
| Name | Required | Description | Default |
|---|---|---|---|
| widgetId | Yes | ID of the widget |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It only implies a read operation via 'Get' but does not disclose any behavioral details such as authentication requirements, rate limits, or side effects. The minimal information may lead to incorrect assumptions about side effects.
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 a single concise sentence with no redundant words. Every element is necessary, and it is front-loaded with the verb and resource.
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 that the tool has only one well-described parameter and no output schema, the description is minimally adequate. However, it could benefit from clarifying what the parameter mappings represent or how they are used, which would improve completeness 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?
The schema already provides 100% coverage for 'widgetId' with a description 'ID of the widget'. The tool description adds no additional meaning beyond what the schema offers, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get' and the resource 'parameter mappings for a widget'. It is specific and directly indicates what the tool does, though it does not explicitly distinguish from related sibling tools like 'get_widget' or 'get_dashboard_parameters'.
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 guidance is provided on when to use this tool versus alternatives such as 'update_widget_parameter_mappings' or other retrieval tools. The description lacks contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all alerts in Redash
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description fails to mention any behavioral aspects like pagination, rate limits, or authentication requirements; beyond being a read operation, it adds nothing.
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?
Single sentence, front-loaded, no extraneous words; appropriately concise for a simple list-all tool.
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?
Despite having no parameters, the description does not clarify the return format or scope (e.g., all alerts across all users or only current user's alerts); with no output schema, this leaves ambiguity.
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?
No parameters exist, so the description does not need to explain them; baseline 4 applies as schema coverage is trivially 100%.
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 clearly states the action 'List' and the resource 'alerts in Redash', distinguishing it from sibling tools like get_alert (single) and create_alert.
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 guidance on when to use this tool vs alternatives such as get_alert or get_alert_subscriptions; no context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available dashboards in Redash
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (starts at 1) | |
| pageSize | No | Number of results per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose pagination or result ordering. It only says 'list' without mentioning that results are paginated (despite schema having page/pageSize). No behavioral traits beyond the literal action.
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?
Single sentence, front-loaded action, no filler words. Efficient and to the point.
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?
Lacks output schema or description of return fields. For a list tool, knowing what fields per dashboard are returned (e.g., id, name, slug) is important. Also no mention of sorting or filtering.
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 100%, so parameters are already described. The description adds no additional meaning beyond what the schema provides, remaining at baseline.
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 clearly states the action (list) and resource (dashboards) but lacks specificity to differentiate from sibling tools like get_favorite_dashboards or get_my_dashboards. 'All available' is ambiguous.
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 guidance on when to use this tool versus alternatives such as get_dashboard or get_my_dashboards. No context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available data sources in Redash
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation by using 'List', which aligns with the typical behavior. No annotations exist, so the statement is clear and accurate, though it could mention safety (e.g., no side effects).
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?
A single, direct sentence with no extraneous words. It efficiently conveys the purpose without redundancy.
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 zero parameters, no output schema, and a straightforward operation, the description fully covers what an agent needs to know to use this tool correctly.
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?
No parameters are defined, so the description adds no parameter-level details. This is acceptable as there is nothing to clarify, achieving the baseline score.
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 clearly states the action ('List') and the resource ('all available data sources in Redash'), distinguishing it from sibling list tools like 'list_alerts' or 'list_dashboards'.
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?
While no explicit when-to-use or alternatives are provided, the description is self-explanatory. For a simple listing tool, this is sufficient, though context about prerequisites could be added.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all alert notification destinations (email, Slack, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description only states the action without disclosing any behavioral traits such as authentication needs, rate limits, or side effects.
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 extremely concise with a single sentence that is front-loaded with the core action and examples, containing no unnecessary words.
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 simple zero-parameter list tool, the description is largely sufficient, though it lacks details about the output structure (e.g., fields returned), which is not covered by an output schema.
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?
With no parameters, the description adds meaning by specifying the resource type (alert notification destinations), which is not detailed in the empty input 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?
The description clearly states it lists all alert notification destinations with examples (email, Slack), making the purpose specific and distinct from sibling tools like list_alerts which list alerts themselves.
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 usage guidelines are provided; there is no mention of when to use this tool versus alternatives or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available queries in Redash
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Search query | |
| page | No | Page number (starts at 1) | |
| pageSize | No | Number of results per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states 'list all available queries' without disclosing pagination, filtering behavior, authentication requirements, or what constitutes 'available'. The bare minimum is provided.
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 a single sentence, which is concise, but it does not earn its place by adding value beyond the tool name. For a listing tool with optional parameters, it is minimally adequate.
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 no output schema and three parameters, the description lacks details on return format, pagination behavior, and result structure. It feels incomplete for effective use.
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 100% with parameter descriptions in the schema. The description adds no additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
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 clearly states 'List all available queries in Redash', specifying a verb (list) and resource (queries). It distinguishes from siblings like get_query (single query) and get_my_queries (personal queries), though 'all available' is slightly 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?
The description provides no guidance on when to use this tool versus alternatives like get_my_queries or get_favorite_queries. It does not mention exclusions or best practices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all reusable query snippets
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must convey behavior. It says 'List all' but doesn't mention pagination, limits, or potential large result sets. Adequate given simplicity but could be more transparent.
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?
A single sentence that efficiently conveys the tool's purpose with no unnecessary words.
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 tool has no parameters and no output schema, the description is sufficient for a simple list operation. It could hint at return format but remains complete enough.
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?
No parameters exist; schema coverage is 100%. The description adds no parameter info beyond schema, so baseline 3 is appropriate.
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 clearly states the tool lists all reusable query snippets, with a specific verb and resource. It distinguishes from siblings like get_query_snippet (single) and create_query_snippet.
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 (when you need all snippets) but provides no explicit guidance on when not to use it or alternatives like get_query_snippet for a single snippet.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all widgets
| Name | Required | Description | Default |
|---|---|---|---|
No 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. It only states the function without disclosing behaviors like pagination, permissions, return format, or absence of side effects. While it implies a read operation, it lacks depth.
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 a single, clear sentence with no wasted words. It is appropriately concise for its simplicity.
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 simple list tool with no parameters and no output schema, the description is adequate but minimal. It does not specify the return type (e.g., list of IDs vs. full objects) or any defaults, leaving some ambiguity for the 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?
There are zero parameters, with schema coverage at 100%. The description adds no parameter details, which is acceptable as no parameters exist. Baseline for zero parameters is 4, and the description aligns with 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?
The description 'List all widgets' clearly states the action (list) and resource (widgets). It is specific and distinguishes from sibling tools like get_widget (single widget retrieval) and create/update/delete widgets.
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 guidance is provided on when to use this tool instead of alternatives like get_widget or other list tools. The agent has no information about appropriate contexts or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mute an alert to temporarily stop notifications
| Name | Required | Description | Default |
|---|---|---|---|
| alertId | Yes | ID of the alert to mute |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies the muting is temporary and reversible, but does not explain how to unmute, duration, or side effects. Without annotations, the description carries the burden and is only partially transparent.
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?
One sentence, very concise, no fluff. However, it lacks any structure (e.g., sections) but is appropriate for the simplicity.
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 simple tool with one parameter and no output schema, the description is adequate but could be more complete (e.g., specifying temporary nature, how to revert). Meets minimum expectations.
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 100% for the single parameter. The description does not add additional meaning beyond the schema's parameter description, so baseline is appropriate.
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 clearly states the action ('Mute an alert') and the purpose ('temporarily stop notifications'). It distinguishes from sibling tools like delete_alert (permanent) and update_alert (changing settings).
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 guidance on when to use this tool versus alternatives (e.g., update_alert for permanent changes, delete_alert for removal). No prerequisites or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unsubscribe from an alert
| Name | Required | Description | Default |
|---|---|---|---|
| alertId | Yes | ID of the alert | |
| subscriptionId | Yes | ID of the subscription to remove |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description lacks behavioral details such as idempotency, error handling (e.g., subscription not found), ownership requirements, or whether the action is irreversible. The minimal description does not compensate for the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence, front-loading the key action. However, it sacrifices some completeness for brevity; a slightly longer description could improve clarity without losing conciseness.
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 simplicity of the tool (2 required params, no output schema), the description is insufficient for safe usage. It fails to mention what happens upon removal, error states, or how to obtain the required IDs, leaving significant gaps in context.
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?
The input schema covers both parameters with clear descriptions (alertId and subscriptionId), and the description adds no additional semantics beyond the schema. Since schema coverage is 100%, a baseline of 3 is appropriate.
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 'Unsubscribe from an alert' clearly indicates the action (unsubscribe) and resource (alert subscription), effectively distinguishing it from sibling tools like add_alert_subscription and get_alert_subscriptions. However, it could be more specific about removing a subscription by ID rather than just unsubscribing.
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 guidance is provided on when to use this tool versus alternatives such as delete_alert or mute_alert. There is no mention of prerequisites (e.g., needing to obtain the subscription ID via get_alert_subscriptions) or exclusions, leaving the agent uncertain about proper usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a dashboard from favorites
| Name | Required | Description | Default |
|---|---|---|---|
| dashboardId | Yes | ID of the dashboard to remove from favorites |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only restates the action without additional details like side effects, permissions, or reversibility.
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?
One short sentence, no wasted words, front-loaded with the verb and noun.
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 simple tool with one parameter and no output schema, the description is adequate but lacks usage and behavioral context.
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 100% and the parameter description already says 'ID of the dashboard to remove from favorites'. The description adds no new meaning.
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 clearly states the action (remove) and the resource (dashboard from favorites), distinguishing it from siblings like add_dashboard_favorite (add) and remove_query_favorite (different resource).
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 guidance on when to use this tool vs alternatives (e.g., archive_dashboard). No prerequisites, context, or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a query from favorites
| Name | Required | Description | Default |
|---|---|---|---|
| queryId | Yes | ID of the query to remove from favorites |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states the action without additional behavioral details like idempotency, permissions, or error conditions.
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?
Single sentence, no unnecessary words. Perfectly concise.
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?
Simple tool with one parameter and no output schema. Description covers the essential purpose. Could mention idempotency or error handling, but overall adequate.
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 100%. Parameter 'queryId' has a clear description. Description adds no extra meaning 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?
Description clearly states the action 'Remove' and the resource 'a query from favorites'. This distinguishes it from the sibling 'add_query_favorite'.
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 guidance on when to use this tool vs alternatives. The action is obvious, but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing alert in Redash
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New name of the alert | |
| rearm | No | Number of seconds to wait before triggering again | |
| alertId | Yes | ID of the alert to update | |
| options | No | Alert options | |
| query_id | No | ID of the query to monitor |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral details, but it only says 'Update an existing alert'. It does not mention merge vs replace behavior, required permissions, or side effects on subscriptions.
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 a single, concise sentence that front-loads the core action without any unnecessary words.
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?
Despite decent schema coverage, the description lacks context about tool behavior, error cases, or confirmation of updates. With 5 parameters and no output schema, it feels incomplete.
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 100%, so parameters are well-documented in the schema. The description adds no extra context about parameters, but baseline is 3 due to high coverage.
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 clearly states the verb 'update' and the resource 'existing alert', distinguishing it from sibling tools like create_alert and delete_alert.
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 provides no guidance on when to use this tool versus alternatives, such as create_alert or get_alert, nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update chart-specific visualization options and merge them with the current Redash chart config by default
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name of the visualization | |
| type | No | Type of visualization | |
| sortX | No | Sort the X axis | |
| sortY | No | Sort heatmap values | |
| xAxis | No | X axis settings | |
| yAxis | No | Y axis settings | |
| legend | No | Legend settings | |
| series | No | Series-wide chart settings | |
| error_y | No | Error bar settings | |
| piesort | No | Sort pie slices | |
| reverseY | No | Reverse heatmap order | |
| sizemode | No | Bubble size mode | |
| direction | No | Pie chart direction settings | |
| lineShape | No | Line interpolation | |
| enableLink | No | Enable click-through links | |
| linkFormat | No | Click-through URL template | |
| showpoints | No | Show all points for box charts | |
| textFormat | No | Data label template | |
| coefficient | No | Bubble size coefficient | |
| description | No | Description of the visualization | |
| swappedAxes | No | Swap the chart axes | |
| chartOptions | No | Raw Redash chart options to merge into the payload | |
| color_scheme | No | Color palette name | |
| numberFormat | No | Number format | |
| columnMapping | No | Column mappings such as x, y, and series | |
| percentFormat | No | Percent format | |
| seriesOptions | No | Per-series settings keyed by series name | |
| valuesOptions | No | Per-value settings | |
| dateTimeFormat | No | Date/time format | |
| linkOpenNewTab | No | Open click-through links in a new tab | |
| replaceOptions | No | Replace the entire options payload instead of merging with the current config | |
| showDataLabels | No | Toggle data labels | |
| visualizationId | Yes | ID of the visualization to update | |
| alignYAxesAtZero | No | Align left and right Y axes at zero | |
| globalSeriesType | No | Chart type | |
| missingValuesAsZero | No | Convert missing values to zero |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It indicates a mutation (update) and default merge behavior, but fails to disclose destructive potential, side effects, auth requirements, or rate limits. Minimal behavioral context.
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?
Single sentence, no fluff. Front-loads the core action and key behavior. Every word earns its place.
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?
With 36 parameters, no output schema, and no annotations, a one-sentence description is insufficient. It does not explain the merge mechanism, the effect of replaceOptions, or the significance of visualizationId. Lacks depth for a complex 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 has 100% description coverage, so baseline is 3. The description adds a hint about merging behavior but does not elaborate on individual parameters beyond what the schema already provides.
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 clearly states the verb 'update', the resource 'chart-specific visualization options', and the key behavior 'merge with current config by default'. It distinguishes from siblings like update_visualization by specifying chart-specific.
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 guidance on when to use this tool versus alternatives like update_visualization. No prerequisites, exclusions, or context provided. The description only implies usage context via 'chart-specific'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing dashboard in Redash
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New name of the dashboard | |
| tags | No | Tags for the dashboard | |
| is_draft | No | Whether the dashboard is a draft | |
| dashboardId | Yes | ID of the dashboard to update | |
| is_archived | No | Whether the dashboard is archived | |
| dashboard_filters_enabled | No | Whether dashboard filters are enabled |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral traits. It only states 'update', implying mutation, but omits details about side effects, permissions required, reversibility, or any consequences of the update.
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 a single sentence, which is concise but lacks structure. It could include more context (e.g., that updates are partial or full) without becoming verbose, achieving a middle ground.
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 6 parameters, no output schema, and no annotations, the description fails to explain the return value (e.g., updated dashboard object), prerequisites, or the scope of the update. It is incomplete for effective tool selection.
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 100%, so the input schema already documents all parameters. The description adds no additional meaning beyond the schema, meeting the baseline expectation for high coverage.
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 clearly states the verb 'Update' and resource 'existing dashboard'. It specifies the tool's purpose but does not differentiate it from sibling tools like archive_dashboard or fork_dashboard, which also modify dashboards in specific ways.
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 guidance is provided on when to use this tool versus alternatives such as archive_dashboard (for archival) or create_dashboard (for new ones). The description lacks any context about appropriate scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move or resize multiple widgets on a dashboard in one call and report per-widget outcomes
| Name | Required | Description | Default |
|---|---|---|---|
| widgets | Yes | Widgets to move or resize | |
| dashboardId | Yes | ID of the dashboard |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it moves/resizes and reports per-widget outcomes, which is good given no annotations. But lacks details on side effects, authentication, or partial failure 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?
Single sentence, front-loaded with verb and resource, no fluff. Every word is functional.
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 tool with two well-schemed parameters and no output schema, the description covers the core functionality and outcome. Lacks details on error handling or limits but is sufficient for basic use.
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 100%, so baseline 3. Description adds context of batch operation and per-widget outcomes but does not elaborate on parameter meanings beyond 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?
The description clearly states the action (move or resize multiple widgets in one call) and the resource (dashboard layout). It distinguishes from sibling tool update_widget_layout which operates on a single widget.
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?
Implies that for multiple widgets, use this tool; for single widget, use update_widget_layout. However, it does not explicitly mention when not to use or provide alternatives beyond the sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update dashboard parameter values and ordering
| Name | Required | Description | Default |
|---|---|---|---|
| parameters | No | Dashboard parameter values to merge into the dashboard | |
| dashboardId | Yes | ID of the dashboard | |
| globalParamOrder | No | Explicit display order for dashboard parameters | |
| replaceParameters | No | Replace the stored parameter list instead of merging | |
| removeParameterNames | No | Dashboard parameter names to remove from the dashboard |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden for behavioral disclosure. It only says 'Update' without detailing side effects, merge vs replace behavior, authorization requirements, or impact on other users. The term 'values and ordering' omits the ability to remove parameters (schema has removeParameterNames).
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 a single, clear sentence with no wasted words. It efficiently conveys the core action, though it could benefit from slightly more context without becoming verbose.
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 mutation tool with 5 parameters and no output schema or annotations, the description lacks essential context such as how the update works (merge vs replace), the effect of globalParamOrder, error conditions, and return behavior. It is insufficient for an AI agent to use 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?
The input schema provides full descriptions for all 5 parameters (100% coverage), so the description adds no additional parameter meaning. Baseline score of 3 is appropriate.
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 clearly states the action ('Update') and the resource ('dashboard parameter values and ordering'), distinguishing it from sibling tools like get_dashboard_parameters and update_query_parameters.
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 guidance is provided on when to use this tool versus alternatives (e.g., get_dashboard_parameters for reading, or update_query_parameters for query-level parameters). Prerequisites are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing query in Redash
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New name of the query | |
| tags | No | Tags for the query | |
| query | No | SQL query text | |
| options | No | Query options | |
| queryId | Yes | ID of the query to update | |
| is_draft | No | Whether the query is a draft | |
| schedule | No | Query schedule | |
| description | No | Description of the query | |
| is_archived | No | Whether the query is archived | |
| data_source_id | No | ID of the data source to use |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'update', which implies mutation but does not explain partial vs full replacement, side effects, permissions, or error conditions.
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 a single short sentence, which is concise. However, it could include more useful information without becoming verbose.
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 complexity (10 params, nested objects) and no output schema, the description is far too minimal. It does not explain update semantics or typical usage, making it incomplete.
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 100%, so the schema already documents all 10 parameters. The description adds no additional meaning beyond 'update', which is baseline acceptable.
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 clearly states the verb 'Update' and the resource 'existing query in Redash'. It distinguishes from sibling tools like 'create_query' and 'archive_query', though 'update_query_parameters' also exists.
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 guidance on when to use this tool versus alternatives, no prerequisites mentioned, and no exclusions. The agent gets no help deciding between update_query and other update tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a query's saved parameter definitions
| Name | Required | Description | Default |
|---|---|---|---|
| queryId | Yes | ID of the query | |
| parameters | No | Parameter definitions to merge into the query | |
| replaceParameters | No | Replace the stored parameter list instead of merging | |
| removeParameterNames | No | Saved parameter names to remove from the query |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the purpose but does not explain default behavior (merging vs replacing), side effects (e.g., removing parameters not mentioned), or authorization requirements. The input schema hints at replace/remove options, but the description lacks an overview.
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 a single sentence, which is concise but lacks structure. It could benefit from brief notes on key parameters (e.g., replaceParameters) or a summary of behavior. It is minimally adequate.
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 tool has complex parameters (merge vs replace, remove) and no output schema or annotations, the description is insufficient. It does not explain how these operations work together or what the expected outcome is, which is critical for safe usage.
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 100%, so the baseline is 3. The description adds no extra meaning beyond the schema; it merely restates the tool's purpose. The schema descriptions are detailed, so no points deducted.
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 uses a clear verb-resource pair: 'Update a query's saved parameter definitions'. It explicitly specifies the resource (query's saved parameters) and distinguishes from sibling tools like 'update_query' (which updates the query itself) and 'get_query_parameters' (read-only).
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 guidance on when to use this tool vs alternatives like 'update_query' or 'create_query'. There is no mention of prerequisites, frequency, or when merging vs replacing parameters is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing query snippet
| Name | Required | Description | Default |
|---|---|---|---|
| snippet | No | The SQL snippet content | |
| trigger | No | Trigger keyword for the snippet | |
| snippetId | Yes | ID of the snippet to update | |
| description | No | Description of the snippet |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description only repeats 'update' without disclosing any behavioral traits such as required permissions, idempotency, or side effects.
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 a single concise sentence, but it could be structured to include key details like required fields or expected outcomes.
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 mutation tool with no annotations and no output schema, the description fails to provide sufficient context about return values, required fields, or behavioral effects.
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 100% with descriptions for all four parameters, so the description adds no additional meaning beyond what the schema provides.
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 clearly states 'Update an existing query snippet', specifying the verb and resource, and distinguishes it from siblings like create, delete, and get.
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 guidance on when to use this tool versus alternatives, no prerequisites or when-not-to-use conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing visualization
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name of the visualization | |
| type | No | Type of visualization. Available types depend on your Redash instance. | |
| options | No | Visualization-specific configuration. The structure depends on your Redash instance and visualization type. Use get_visualization to see the current configuration before updating. | |
| description | No | Description of the visualization | |
| visualizationId | Yes | ID of the visualization to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It only states 'update', implying mutation, but does not disclose permissions, idempotency, error states, or side effects. The lack of any behavioral details reduces transparency significantly.
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 a single, short sentence, which is concise. However, it is so brief that it lacks substance; it does not elaborate on the purpose beyond the obvious. It earns its place minimally.
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 complexity (5 parameters, nested objects, no output schema), the description is severely incomplete. It does not explain what the tool returns, how errors are handled, or how to use it effectively. The schema covers parameters but not the overall behavior.
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 100%, so the schema already documents all parameters adequately. The tool description adds nothing beyond the schema, resulting in a baseline score of 3.
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 'Update an existing visualization' clearly identifies the action and resource, using a specific verb and indicating that it operates on an existing entity. However, it does not differentiate from sibling tools like 'create_visualization' or 'update_chart_visualization'.
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 provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusionary conditions. Users are left to infer based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing widget
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Text content for text widgets | |
| width | No | Width of the widget (1-6) | |
| options | No | Widget options | |
| position | No | ||
| widgetId | Yes | ID of the widget to update | |
| visualization_id | No | ID of the visualization to display |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits, but it only says 'update'. It does not disclose whether the update is partial or full replacement, what happens to unspecified fields, required permissions, or side effects. This is insufficient for safe tool use.
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 very short (5 words), which is concise but lacks structure. It does not front-load crucial information such as update behavior or scope. While efficient, it sacrifices clarity for brevity.
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 tool's complexity (6 parameters, nested objects, no output schema) and the presence of closely related sibling tools, the description is incomplete. It does not explain the update scope, error conditions, or return values, leaving the agent with insufficient context to use the tool correctly.
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 high (83%), and the input schema provides descriptions for most parameters. The tool description adds no extra meaning beyond what is already in the schema, so it meets a baseline but provides no added value.
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 'Update an existing widget', which is a clear verb+resource. However, it does not differentiate from sibling tools like 'update_widget_layout' or 'update_widget_parameter_mappings', which also update aspects of a widget. Thus, the purpose is somewhat vague for an agent to choose this tool over alternatives.
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 provides no guidance on when to use this tool versus sibling tools (e.g., create_widget, update_widget_layout, delete_widget). No context or conditions for use are given, leaving the agent without criteria for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move or resize a single widget by updating its grid position
| Name | Required | Description | Default |
|---|---|---|---|
| position | Yes | ||
| widgetId | Yes | ID of the widget |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It states that the tool moves or resizes, implying mutation, but does not disclose permissions, idempotency, side effects, or error handling. The behavior of partial vs. full position replacement is unclear.
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 a single, front-loaded sentence of 12 words, which is concise. However, it sacrifices valuable context that could be added without becoming verbose.
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 no output schema, no annotations, and nested parameters, the description is incomplete. It does not explain the grid system, constraints, or what happens on success/failure. The tool's mutation aspect and parameter structure are under-described.
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 50% (the 'position' object lacks a description). The description only mentions 'grid position' without elaborating on the sub-fields (col, row, sizeX, sizeY, autoHeight) or their constraints. It fails to add meaning beyond what the schema provides.
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 uses specific verbs 'Move or resize' and identifies the resource 'single widget' and the affected attribute 'grid position'. It clearly distinguishes from sibling tools like 'update_widget', which likely updates other properties.
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 provides no guidance on when to use this tool over alternatives, such as 'update_widget' for non-layout changes. No prerequisites or conditions for use are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a widget's parameter mappings
| Name | Required | Description | Default |
|---|---|---|---|
| widgetId | Yes | ID of the widget | |
| parameterMappings | No | Parameter mappings to merge into the widget | |
| removeParameterNames | No | Widget parameter mapping names to remove | |
| replaceParameterMappings | No | Replace the stored mappings instead of merging |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states 'Update', which implies mutation but does not disclose details like merge vs replace behavior, potential side effects, or required permissions. With no annotations, the description should provide more context, but it falls short.
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 very concise (one sentence), but it lacks explanatory detail for a tool with a non-trivial schema. It could be more informative without being verbose, so it scores average.
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 complexity of the parameter mappings (array of objects with various fields) and the lack of an output schema, the description is insufficient for an agent to fully understand the tool's behavior, such as how mappings are merged or what happens when both 'parameterMappings' and 'removeParameterNames' are provided.
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 100%, so the baseline is 3. The description adds no additional meaning beyond the schema; it does not explain the merge/replace logic or the role of 'removeParameterNames'. The agent must rely solely on parameter descriptions 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?
The description explicitly states 'Update a widget's parameter mappings', clearly indicating the action and resource. This distinguishes it from sibling tools like 'update_widget' (which updates general widget properties) and 'get_widget_parameter_mappings' (read-only).
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 guidance is provided on when to use this tool versus alternatives, such as 'update_widget' or direct parameter mapping modifications. There are no prerequisites or exclusions mentioned, leaving the agent to infer context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a specific resource and action, with clear distinctions even among similar operations (e.g., execute_query vs execute_adhoc_query). The descriptions further clarify any potential overlap.
All tools follow a consistent verb_noun snake_case pattern (e.g., create_dashboard, get_query, delete_alert). No mixing of conventions or vague names.
67 tools is high but appropriate for a comprehensive BI tool covering alerts, dashboards, queries, visualizations, widgets, snippets, data sources, and destinations. Each entity has a logical set of CRUD and utility tools.
The tool surface covers core workflows for alerts, dashboards, queries, and visualizations. Missing update/delete for data sources and destinations, but these are likely admin-level operations. Otherwise, no significant gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/suthio/redash-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
