d8a.tech

d8a_prepare_insight_change

Prepare creating or updating a table, funnel or journeys insight without saving or running it. content has title, description, kind (table, funnel or journeys), definition_schema_version (1 table, 2 funnel, 3 journeys: it names the type, it is not a newer version) and definition. mode=create needs title, kind, definition_schema_version and the complete definition. mode=update needs insight_id and lock_version from d8a_get_insight_definition and keeps omitted fields; a title or description change keeps the saved definition exactly. A new definition needs its definition_schema_version, and changing the type also needs kind. Table definitions use dimensions, metrics and filters: [[{column: {id}, operator, values: [...]}]] (values, not d8a_run_query's value); dates, paging and comparisons are not saved. Use exact IDs from d8a_get_query_catalog. Show the user the complete before and after and the warnings, ask them to approve, then call d8a_execute_change. Running the insight first is a good check but not required. Insights can't be deleted here.

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": {
      "property_id": "<property_id>",
      "mode": "<mode>",
      "content": "<content>"
    },
    "name": "d8a_prepare_insight_change"
  }
}

Input Schema

Name	Required	Description
`mode`	Yes	create or update.
`content`	Yes	Fields to save; omitted ones stay as saved.
`insight_id`	No	Insight to update; omit when creating.
`property_id`	Yes	Property ID.
`lock_version`	No	From d8a_get_insight_definition.

Output Schema

Name	Required	Description	Default
`review`	No
`target`	Yes
`preview`	Yes
`expires_at`	No
`proposal_id`	No
`requires_acknowledgment`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 6, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond annotations (non-read-only, non-destructive, non-idempotent), it discloses that nothing is persisted or executed, that omitted fields are preserved on update, that a title/description-only change leaves the saved definition untouched, that lock_version guards concurrency, and that dates/paging/comparisons are not saved.

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

Conciseness4/5

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

Front-loads the purpose and the prepare/execute split, then moves into mode requirements and definition syntax. Some parentheticals and run-on clauses ('dates, paging and comparisons are not saved') make it heavier than necessary, but little is wasted.

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

Completeness5/5

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

For a two-mode, nested-object mutation tool with an approval workflow, the description covers preconditions, data sourcing, field-merge behavior, validation constraints, and the required next step. An output schema exists, so return values need no explanation.

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

Parameters4/5

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

Schema coverage is already 100%, yet the description still adds real meaning: the mapping of definition_schema_version 1/2/3 to kind and the clarification that it names the type rather than a newer version, plus the 'values' vs d8a_run_query's 'value' distinction. Slightly dense but the added semantics are genuine.

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?

Opens with a specific verb and resource ('Prepare creating or updating a table, funnel or journeys insight') plus the key scope distinction 'without saving or running it', which separates it from d8a_execute_change and the run_* siblings.

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

Usage Guidelines5/5

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

Explicitly states the create-vs-update requirements, when to pull IDs from d8a_get_query_catalog and lock_version from d8a_get_insight_definition, and the routing rule: show the user before/after plus warnings, get approval, then call d8a_execute_change. It also excludes deletion and notes that running first is optional.

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

All d8a.tech tools Inspect

Try in Browser

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?