Skip to main content
Glama

Datasource Refresh Fields

datasource_refresh_fields
Destructive

Syncs a datasource's fields with its connector: adds new columns, drops removed ones, and preserves existing field edits. Previews changes by default and blocks removal of fields still in use.

Instructions

Refresh fields from the connector, as the datasource editor's REFRESH FIELDS does.

New columns become fields with the connector's defaults. Fields whose column is gone are removed; if a formula or the report in scope uses one, the refresh is blocked unless allow_in_use=true. Surviving fields keep every edit (labels, types, aggregation, descriptions); a column whose type changed is listed in retyped_columns, not retyped. Preview by default; publication is journaled, read back and reversible with operation_restore. Single-connector sources only.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "datasource_id": "<datasource_id>",
      "expected_fingerprint": "<expected_fingerprint>"
    },
    "name": "datasource_refresh_fields"
  }
}

Input Schema

NameRequiredDescriptionDefault
dry_runNo
report_idNo
allow_in_useNo
datasource_idYes
allow_shared_sourceNo
expected_fingerprintYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.6.5

TDQS

A4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is partly carried elsewhere, but the description still adds substantial value: new/deleted fields, preserved edits, retyped columns listed rather than mutated, and journaled/reversible publication. It does not explain expected_fingerprint or allow_shared_source, which are the two parameters most relevant to whether a destructive refresh is actually allowed.

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

Conciseness5/5

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

Dense, front-loaded, and structured as outcome → blocking condition → preservation rules → reversibility → scope limit. No sentence is redundant, and the constraint about single-connector sources is placed last where it acts as a guard rather than a preamble.

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

Completeness4/5

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

An output schema exists, so return-shape explanation is rightly omitted, and the destructive semantics are covered well. Incompleteness comes from the undocumented fingerprint and shared-source parameters, and from not stating what a blocked refresh returns, which an agent would want before invoking a destructive operation.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must carry all meaning, and it only partly does: dry_run (preview by default), allow_in_use, and report_id ('the report in scope') are covered, while expected_fingerprint and allow_shared_source are never mentioned. Two of six parameters remain opaque, which is a real gap for a destructive tool.

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

Purpose5/5

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

States a specific verb and resource ('Refresh fields from the connector') and anchors it to a familiar UI action (the datasource editor's REFRESH FIELDS). The closing scope clause ('Single-connector sources only') separates it from blend and calculated-field siblings without needing to name them.

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

Usage Guidelines4/5

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

Gives clear operating context: preview by default, publication is journaled and reversible via operation_restore, and refresh is blocked when a formula or in-scope report uses a removed column unless allow_in_use=true. Missing explicit routing to alternatives such as datasource_calculated_fields_* or datasource_fields_edit_metadata when a user only wants to edit metadata.

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

Deploy Server

Other Tools