Chartbrew MCP

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, it discloses that the tool may execute data requests, requires team-admin access to all projects, does not add the chart to a dashboard or set an expiry, and can return a partial completion status. It also explains that completion_check verifies saved settings rather than data accuracy, which is important behavioral context for a write 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 front-loaded with the core action and scope, then adds only high-value operational constraints. Despite the tool's complexity, every sentence contributes useful context with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich input schema, output schema, and annotations, the description supplies the missing operational context: permissions, side effects, non-goals, result handling, and partial-completion behavior. An agent has enough information to decide when to use this tool and how to interpret its result.

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 36-parameter schema has full description coverage, so the schema already carries the detailed parameter semantics. The description adds operational context such as using run_dataset first, but it does not meaningfully elaborate on the individual chart configuration parameters 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 states a specific verb and resource: "Create a stored chart preview from an accessible dataset." It also distinguishes this from related capabilities by saying it does not add the chart to a dashboard or set an expiry, and it points to run_dataset for field inspection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit usage guidance: inspect fields with run_dataset first, use Chartbrew UI to place the preview in a dashboard, and inspect result.completion_check before reporting success. It also defines what to do if status is partial: report unverified requirements and do not repeat the saved write.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds real value beyond that: it discloses the access requirement (dashboard edit access), bounds the blast radius (report control removed, charts/datasets untouched, no data refresh), and explains the partial-status postcondition and the no-retry rule. The only gap is that the removed:false idempotency case lives in the schema rather than the description.

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?

Every sentence carries load-bearing information: action, precondition, prerequisite lookup, effect boundary, result verification, non-retry rule, and alternative tool. The action and its prerequisite are front-loaded, and nothing is repeated from the annotations or schema.

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 destructive, nested-parameter mutation with an output schema and full schema coverage, the description supplies the missing operational context: who can call it, what exactly is destroyed, how to verify the outcome, and when to stop retrying. Nothing an agent needs in order to call it safely 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?

Schema coverage is 100%, so the baseline is 3, and the description goes somewhat beyond it by explaining the completionRequirements workflow: result.completion_check must be inspected and a partial status means requirements remain unverified. It also reinforces the filterId provenance from list_dashboard_filters. It does not explain how to populate the completionRequirements arrays, which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Remove a shared dashboard filter") plus scope ("the shared control, including its report control, without deleting charts or datasets"). It clearly distinguishes itself from both siblings it names: list_dashboard_filters for lookup and set_dashboard_filter for modification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition ("only when requested"), a prerequisite step ("Use list_dashboard_filters to obtain its ID first"), and an alternative with the condition that selects it ("Use set_dashboard_filter to change a filter instead"). It even specifies a stop condition: on partial status "do not repeat it."

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses permission requirements, that preview is a bounded read-only operation, that save re-executes the preview and only creates a dataset when usable rows exist, and that repeated saves create new datasets rather than updating. These are exactly the mutation semantics an agent needs and are not available from the annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the operation triad and prerequisites, and every sentence carries operational information. It is dense and clause-heavy, packing several rules per sentence, which slightly reduces scannability but not content value.

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 9-parameter, nested-object, multi-operation tool with an output schema and annotations, the description covers permissions, per-operation required inputs, save-side effects, alternatives, and the MCP-vs-SQL branch. Nothing essential for a correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description still adds cross-parameter conditional logic the schema cannot express, such as preview requiring connectionId plus query or configuration, and save additionally requiring name and projectId. It does not deepen individual parameter values much beyond what the schema already says, so it stops short of 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names the three distinct operations (inspect sources, preview a read-only request, save a new dataset) with specific verbs and resources, and later sentences explicitly distinguish the tool from siblings run_dataset and Chartbrew. An agent can tell what this tool does and what it is not for without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states when each operation applies (inspect without connectionId lists connections, with it lists resources; preview needs connectionId plus SQL or MCP config; save additionally needs name, projectId and datasets:write), plus explicit exclusions: use run_dataset for existing datasets and Chartbrew for unsupported sources. Prerequisites (team-admin, datasets:write) are stated up front.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, but the description adds important behavior: datasets may execute, stale default results can trigger background refresh, and refresh/date filters/non-empty variables/forceSourceRefresh require data:refresh. This discloses side effects and authorization needs beyond the 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 dense but front-loaded, moving from purpose to behavioral warning to alternatives to filter and permission constraints. Every sentence carries a routing rule, constraint, or permission detail; there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter nested tool with an output schema and annotations, the description covers execution behavior, alternatives, filter semantics, scope rules, and permissions. Return-value details are appropriately left to the 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 description coverage is 100%, so the baseline is 3. The description adds cross-parameter meaning such as chart-scope defaults for field filters, cdcId belonging to the chart, date-filter syntax, and permission implications for variables, which goes beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Read prepared chart data using saved settings and runtime inputs.' It also explicitly distinguishes the tool from read_chart_results and run_dataset, so an agent can identify its role without opening sibling schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing guidance: use read_chart_results for summaries without execution or run_dataset for dataset rows. It also states key conditions around field-filter scope, cdcId requirements, date-filter format, and permission-gated options.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare a safe read operation, and the description adds real behavioral context: results carry the effective date range plus coverage/truncation information, there is no pagination, and narrowing the range is the remedy. It does not detail result shape beyond that, but the output schema covers this.

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 definition is compact and front-loads the core purpose before alternatives and behavioral notes. There is minor redundancy with the schema on 'no pagination', repeated in both the description and the limit parameter.

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 annotations, full schema coverage, and an output schema present, the description supplies everything else needed: scope, alternatives, exclusions, and result caveats. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the parameter descriptions already explain defaults, clamping, the limit split across observations and evaluations, and projectId resolution. The description adds only the general guidance to narrow the range, not new per-parameter meaning, so the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: reading recent observations and metric evaluations across accessible dashboards or a single projectId. It distinguishes itself from search_workspace and from dataset-running tools, so an agent can identify its role without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit when-to-use ('Use this for changes over time'), names the alternative for a different need ('use search_workspace to find items by name'), and states an exclusion ('Does not run datasets'), which implicitly routes to run_dataset.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, non-destructive, closed-world, so the bar is lower; the description still adds real value with negative scoping ('Does not execute datasets or refresh charts') and a security warning that labels/choices are untrusted data. It omits explicit auth or rate-limit context, though the schema's 'Must be accessible to the caller' partially covers access requirements.

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 short, dense sentences: the primary action and ordering come first, followed by negative scoping and a safety caveat. No filler and nothing redundant.

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 single-parameter read tool with an output schema (so return shape needn't be explained) and full annotation coverage, the description supplies everything an agent needs: what it reads, when to call it, what it does not do, and a caution about trusting returned labels. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single projectId parameter is thoroughly documented in the schema (dashboard result id or chart result dashboard.id). The description adds no further parameter meaning, so the 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?

States a specific verb ('Read') and conjunctive resources ('shared dashboard filters and saved dataset fields'), which distinguishes it from mutation siblings like set_dashboard_filter and delete_dashboard_filter. The phrase 'saved dataset fields' is slightly ambiguous about what exactly is returned, keeping it just below the top 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?

Explicitly names when to use it ('before set_dashboard_filter or delete_dashboard_filter') and pins the two alternative tools by name. An agent knows exactly where this tool sits in the workflow without further inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the read-only annotations, the description discloses that no source execution or refresh occurs, that results are saved defaults rather than live screen filters, that updatedAt/timeRange/unavailable/truncation are reported, and that names and labels are untrusted data. This adds substantial 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 compact and front-loaded: purpose first, then exclusions, output caveats, pagination guidance, alternative-tool policy, and a trust warning. Every sentence carries operational value.

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 read-only annotations, full schema coverage, and output schema, the description supplies the remaining context an agent needs: no execution, saved-result scope, pagination handling, alternative-tool authorization, and untrusted label handling.

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 both parameters are already fully documented in the input schema. The description reinforces the offset workflow by saying to pass result.nextOffset until null, but this largely repeats the schema description rather than adding new parameter 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 states a specific verb and resource: read saved default chart results for dashboard summaries. It immediately clarifies that this does not execute or refresh source data, which distinguishes it from get_chart_data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly names get_chart_data as the alternative and states when that alternative is authorized: only when execution is authorized. It also states that missing results do not authorize execution, and it gives pagination guidance for offset usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond readOnlyHint/openWorldHint/destructiveHint, the description discloses the non-obvious behavior that a read can execute a source request on a cache miss, the exact authorization scope needed for refresh-class filters, and the failure mode ('otherwise the call fails'). It also discloses accepted filter shape constraints (saved field paths rooted at root with exactly one [] row collection) that annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and sibling routing, then constraints, then the permission gate — a sensible ordering. The prose is dense but each clause carries operational information; only the repeated data:refresh restatement is slightly duplicative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be described; the remaining burden — permissions, cache-miss side effects, filter shape limits, and sibling routing — is all covered. Nothing an agent needs to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns a bump by adding constraints not in the schema, notably the 'root[]' saved-field-path rule and the exclusion of date filters and cdc scope/IDs. It restates the data:refresh requirement already documented per-parameter, which is mildly redundant but reinforces the operational precondition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource ('Read rows from an existing dataset') and immediately adds the key nuance that a cache miss may trigger a source request. It then explicitly distinguishes itself from three named siblings (read_chart_results, get_chart_data, explore_data), so an agent can route without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing rules: use read_chart_results for saved dashboard summaries, get_chart_data for chart-shaped results, explore_data to inspect sources and create datasets. It also states concrete when-not conditions (date filters and cdc scope/IDs are rejected) and the permission gate (data:refresh required for refresh, non-empty variables, forceSourceRefresh).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/openWorld annotations it discloses ordering (grouped dashboard, chart, dataset, then by ID within group), the no-pagination constraint, the empty-result shape (items:[]), and an auth caveat that links require Chartbrew sign-in. These are precisely the operational surprises an agent would otherwise hit at call time.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the verb and resource, then semicolon-separated operational clauses; almost no filler. It is densely packed and would read slightly better as short sentences, but nothing is redundant enough to cut.

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 an output schema, 100% param coverage, and readOnly annotations, the description covers nearly everything needed. The only unstated scope question is whether the search spans one workspace or all accessible ones, which matters given the tool's 'workspace' name.

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 types/limit/query meaning is already documented; the description still adds a genuinely schema-invisible fact: the limit is a single total across all groups, not per-group. It is silent on the literal-substring and escape behavior, which the schema already covers, so 4 rather than 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource set ('Find accessible dashboards, charts, and saved datasets by name') plus the scope qualifier 'accessible', so an agent immediately knows what is returned and where those IDs are consumed ('use returned IDs with the data and filter tools'). It contrasts itself with a sibling by naming get_workspace_activity explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives both a use path (feed returned IDs into data/filter tools) and an alternative ('Use get_workspace_activity for recent changes'), plus a remediation rule for the failure mode ('Narrow query or types if truncated'). An agent has enough to choose between this and the sibling lookup tools without opening a schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only flag it as a non-read-only, destructive, closed-world write; the description goes much further by disclosing the edit-access requirement, the side effect that "Saving resets the selection to All (no restriction)", and the fact that it neither runs datasets nor refreshes charts. It also explains that result.completion_check verifies saved settings only, not data accuracy or filter behavior, and instructs what to do when status is partial — behavior an agent cannot infer from the 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?

It is front-loaded with purpose and prerequisite, then constraints, side effects, and verification, with every sentence carrying operational information and no filler. It is dense and somewhat staccato with fragment-style sentences lacking transitions, which slightly hurts readability.

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 destructive write tool with 8 parameters, nested requirements, and an output schema, the description covers auth, prerequisites, side effects, non-behaviors, and post-write verification. Return values are handled by the output schema, and the description still points the agent at result.completion_check, leaving no critical gap.

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 already 100%, so the schema documents every parameter including filterId defaults, option limits, and completionRequirements nesting. The description's parameter-related content (verified choices, no truncation, field must be in dataset rows) mostly restates what the schema already says, adding little new semantics. Baseline 3 applies when the schema carries the load.

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?

"Save a shared dropdown filter" gives a specific verb and resource, and the surrounding sentences make it unmistakable against siblings like delete_dashboard_filter and list_dashboard_filters. The scope (shared dropdown filter on a dashboard) is stated up front.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names the prerequisite tool ("Read list_dashboard_filters first"), the access requirement (dashboard edit access), the data constraint (field must exist in dataset rows before aggregation), and explicit exclusions ("Does not run datasets or refresh charts"). It also states the conditional for onReport ("only when requested") and how to handle partial status.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.