TweakThis

Wait for changes

wait_for_changes

Read-onlyIdempotent

Waits until something changes in one project since your cursor, then returns it like list_changes does; with nothing new after timeout_seconds (default 45, at most 270), it returns no changes and a cursor. For working unattended: handle each change (get_feedback, claim_feedback, fix, submit_resolution), then call it again with the latest next_cursor, at once while has_more is true. A cursor is required: get one from list_changes. Keep timeout_seconds below your client's tool timeout; more than 45 seconds usually needs it raised. One wait per project and connection: a new call ends the earlier one, which returns no changes and says so. Not a metered read.

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": {
      "project_id": "<project_id>",
      "cursor": "<cursor>"
    },
    "name": "wait_for_changes"
  }
}

Input Schema

Name	Required	Description
`kinds`	No	Which changes to return. Default: new, answered, reopened, assigned_to_me, revised.
`limit`	No	Changes per call (default and maximum 50).
`cursor`	Yes	next_cursor from list_changes or your previous wait_for_changes call.
`project_id`	Yes	Project id from list_projects.
`session_id`	No	Only items of this review session (the developer gives you its id).
`include_own`	No	Also your own connection's comments, assignments and resolutions. Default false.
`timeout_seconds`	No	How long to wait for a change, in seconds (default 45, at most 270).

Output Schema

Name	Required	Description
`error`	No	Present only when isError is true: a stable error code (not_found, invalid, conflict_stale, conflict_claimed, conflict_state, quota_exhausted, rate_limited, internal_error) with details such as current_revision/current_version.
`changes`	No
`has_more`	No
`next_cursor`	No
`schema_version`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 7, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description discloses timeout bounds, that a new call on the same project/connection cancels the earlier wait and returns no changes with an explicit notice, that timeout_seconds must sit below the client's tool timeout, and that this is not a metered read. These are exactly the concurrency and cost behaviors 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.

Conciseness4/5

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

It is front-loaded with the core semantics and every clause carries operational information, but the long semicolon-chained sentences make it denser than needed and slightly harder to scan on first read.

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 blocking, cursor-driven tool with a concurrency hazard, the description covers the return path (no changes plus a cursor), the has_more loop, the one-wait-per-project rule, and the required cursor source. With an output schema present, it need not re-document structure, and it does not.

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 100%, so the baseline is 3, but the description adds genuine meaning: the cursor's required provenance (list_changes or a previous wait), the practical ceiling on timeout_seconds relative to client tool timeouts, and the return-on-timeout behavior. Remaining parameters like kinds, limit, session_id, and include_own are left to the already-descriptive schema.

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?

The description opens with a specific verb and resource ('Waits until something changes in one project') and explicitly distinguishes itself from list_changes, stating it 'returns it like list_changes does' but blocks until a change arrives. An agent can immediately tell this is the blocking counterpart to list_changes.

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?

It spells out the unattended workflow end to end (handle each change via get_feedback, claim_feedback, fix, submit_resolution, then call again with the latest next_cursor and loop while has_more is true), names list_changes as the source of a required cursor, and explains the alternative of increasing timeout_seconds. Nothing about when-to-use versus siblings is left to inference.

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

All TweakThis 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?