ai-agent-channel

backfill_superseded

Replay the supersede rule on older proposals and nudges settled before the rule existed, retiring them as superseded after a dry-run preview.

Instructions

One-off: replay the supersede rule over rounds settled BEFORE the rule existed. Candidates: proposals for a pin raised before its current version ('key' rows; claimed_by lists every matching key), nudges whose about_message_id target is deleted or superseded ('target' rows), and — only with include_by_reference=true — messages linked to a candidate by a '#N' mention ('reference' rows). A revised proposal is live, not a dead target. dry_run=true (the default) returns exactly what this call would retire: 'key' filters key rows to that key ('target' rows claim no key and stay in), 'ids' narrows further; plus would_cascade (nudges retired along), not_candidates and multi_claimed. To apply, repeat with dry_run=false, the reviewed 'ids', 'expect_count' (= number of ids), and 'key' plus 'word_message_id' — one message per key, sent by that key's owner. Refused: ids that are not candidates of this call, approval records of pin versions, and ids claimed by keys the pass does not name. Retired messages stay readable with a 'superseded_backfill' event; undo_backfill reverses a pass. 'fields' projects the preview rows. Optional 'fields' projects the response: a list of field names, or the single value 'headers' for the usual listing set (everything except the bodies). Omit it and the full record comes back. Use it when a listing over a long history would otherwise be too large to return — bodies dominate the size, and a 'which messages' question rarely needs them; fetch the ones you want individually afterwards.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`ids`	No
`key`	No
`fields`	No
`dry_run`	No
`snapshot_at`	No
`expect_count`	No
`word_message_id`	No
`include_by_reference`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 12, 2026

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses that dry_run is the default and returns a preview, that applying requires repeating with dry_run=false plus expect_count and key/word_message_id, what is refused, and that retired messages remain readable with a 'superseded_backfill' event. Reversibility via undo_backfill is also made explicit.

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?

The description is front-loaded and information-dense, with nearly every sentence adding context. However, the 'fields' sentence is effectively stated twice ('projects the preview rows' and 'Optional fields projects the response'), and the candidate-category layout reads as a long wall of text. Given the 8-parameter complexity, the length is mostly justified.

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?

The description covers the full call lifecycle: candidates, filters, preview content, refusal conditions, application requirements, reversibility, and output projection. Since an output schema exists, return-value details do not need to be restated, but snapshot_at remains unexplained and concepts like would_cascade, not_candidates, and multi_claimed are named without definitions.

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 description coverage is 0%, so the description must compensate, and it does for most parameters: dry_run, ids, key, include_by_reference, expect_count, word_message_id, and fields all receive meaningful explanation. However, snapshot_at is present in the schema but never mentioned, leaving one of eight parameters semantically unaddressed.

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 statement: 'replay the supersede rule over rounds settled BEFORE the rule existed.' It also enumerates distinct candidate categories ('key', 'target', 'reference' rows), which lets an agent understand exactly what the tool acts on and how it differs from siblings like undo_backfill.

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?

It clearly frames the one-off historical backfill use case, explains the dry_run=true preview-then-apply workflow, and names undo_backfill as the reversing operation. It does not explicitly list when-not-to-use alternatives, but the 'BEFORE the rule existed' qualifier and two-phase workflow provide strong contextual guidance.

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