d8a.tech

d8a_prepare_goal_change

Prepare creating or updating a goal without saving it. content has name and conditions: {groups: [[filter, ...], ...]}; groups are alternatives (OR) and the filters in a group must all match (AND). Conditions replace the whole definition. Use exact IDs from d8a_get_query_catalog and an operator it lists for that column, e.g. = or starts_with. mode=create needs name and conditions; mode=update needs goal_id and lock_version from d8a_get_goal and keeps omitted fields. Show the user the complete before and after conditions and the warnings, ask them to approve, then call d8a_execute_change. Editing a goal also changes its results for data already collected. Goals can't be deleted here; don't change goals during weekly reviews or tracking audits unless asked.

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_goal_change"
  }
}

Input Schema

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

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.7/5.0

Behavior4/5

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

Beyond the annotations (which only say non-read-only, non-destructive, non-idempotent), the description discloses that nothing is persisted until d8a_execute_change, that conditions replace the entire definition rather than merging, that editing retroactively changes results for already-collected data, and that deletion is not supported here. These are substantive behavioral facts an agent could not infer from the flags, though it does not say where/how a prepared change is held or whether it expires.

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?

Dense and front-loaded, with the purpose, schema semantics, workflow, and cautions in that order; nearly every clause carries new information. It is delivered as one long unbroken block, which makes the approval workflow and the caution about retroactive results harder to scan than they should be.

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 nested-schema, multi-step mutation workflow this covers prerequisites, identifier sourcing, merge-vs-replace behavior, the required human approval step before d8a_execute_change, and prohibited contexts. With an output schema and full annotation coverage already present, nothing an agent needs in order 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.

Parameters5/5

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

Schema coverage is already 100%, so the baseline would be 3, but the description adds real semantics the schema cannot express: the conditions object shape as {groups: [[filter, ...], ...]}, the OR-across-groups / AND-within-group logic, the replace-not-merge semantics, and the requirement that column IDs and operators come from d8a_get_query_catalog with a supported pairing (e.g. = or starts_with). It also explains lock_version's provenance and mode-specific required fields.

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 plus a critical scope qualifier: 'Prepare creating or updating a goal without saving it.' The agent immediately knows this is a staging/dry-run step and, from the later sentence, that d8a_execute_change is the commit counterpart.

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?

Gives explicit preconditions per mode (create needs name+conditions; update needs goal_id and lock_version from d8a_get_goal), names the required upstream source for identifiers (d8a_get_query_catalog), and adds a negative guideline: don't change goals during weekly reviews or tracking audits unless asked. Alternatives and their triggering conditions are all stated.

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?