Selvedge

Overview Schema Source Related Servers Discussions Admin

Stale decisions due for revisit

stale_decisions

Read-onlyIdempotent

Find decisions due for revisit: expired, past their revisit date, or flagged for review. Get reasons and filters to focus on the right stale decisions.

Instructions

Decisions due for a revisit — expired, past their date, or with a triggered stale condition.

Three deterministic rules. Expiry-based (flag="expired"): events whose expires_when condition fired, evaluated from local state only — date: against now, entity:PATH:changes against the event log, library:NAME>=VERSION against installed dist metadata; the pattern kind that fired is in expired_pattern. A library: condition whose dependency isn't locally observable surfaces as flag="manual_review" instead of a guess; manual:LABEL never auto-fires. Date-based (flag="revisit_due"): events whose revisit_after has passed AND the entity is still live (queried via blame/diff/prior_attempts after the decision, or its changeset saw later activity) — pure age alone never surfaces. Condition-based (flag="review_suggested"): events whose stale_when text shares keywords with a LATER change event — the named invalidation evidence may have happened. Surfacing only: nothing is un-retired automatically; follow up with a supersede if the condition really was triggered. A later supersede that re-opens the candidate (explicit supersedes id, or the same id-less auto-link prior_attempts uses) drops it from this list; a same-path sibling the supersede did not target still surfaces.

Each result is the change event plus flag, revisit_due, days_overdue, active_use_signals, matched_terms, matched_event_id, expires_status, expired_pattern, expires_detail, and a one-line stale_reason. Date-due rows first, most-overdue leading; filter by entity_path, project, or agent. Templated and deterministic; no LLM call, no network.

Input Schema

TableJSON Schema

Name	Required	Description
`agent`	No	Optional filter to the agent that logged the decision.
`limit`	No	Maximum number of results.
`project`	No	Optional filter to a specific project/repository.
`entity_path`	No	Optional filter to a single entity or path prefix — 'users' also covers 'users.email'. Empty = every entity.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.3.11Aug 2, 2026
- addedInput schema / properties / limit / maximum
```
Added value: +1000
```
Addedv0.3.8Jun 17, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Even with annotations marking readOnly, deterministic, and non-destructive, the description adds substantial behavioral detail: no LLM call, no network, no automatic un-retiring, fallback to manual_review when dependency state is unobservable, and effects of later supersede events. This is far beyond what annotations alone convey.

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 longer than average, but the tool has complex deterministic rules and edge cases that warrant the detail. It is front-loaded with the core purpose and organized by flag type, followed by output fields, ordering, and guarantees. The output field enumeration is slightly redundant with the existing output schema, preventing a 5.

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 tool with this complexity, the description is complete: it explains all three surfacing mechanisms, non-obvious edge cases like manual_review, output shape, ordering, filtering, and determinism guarantees. Combined with the rich annotations and output schema, an agent has everything needed to select and invoke the tool correctly.

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 100%, so the baseline of 3 applies. The description mentions filtering by entity_path, project, or agent, which reinforces the schema but does not add much new semantic depth. It does not describe parameter formats beyond what the schema already provides.

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: 'Decisions due for a revisit,' then enumerates the three deterministic rules and their resulting flags. It clearly distinguishes this tool from siblings by emphasizing it is surfacing-only, deterministic, and local-state-based.

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?

The description gives clear context for when results surface: expiry-based, date-based, and condition-based rules, with explicit caveats like 'pure age alone never surfaces' and 'manual:LABEL never auto-fires.' It does not explicitly name sibling alternatives for exclusion, but the behavioral specificity makes intended usage unambiguous.

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

Deploy Server