Heddle is a local-first, advisory-only temporal change-impact authority that tracks per-entity change history across git commits and answers downstream-propagation queries. It never gates or enforces policy — it provides facts to help agents identify what needs re-verification after a change.
Core capabilities:
List changed entities (heddle_change_list / changed): Query which entities changed for a given repo and revision range.
Get entity change timeline (heddle_entity_timeline_get / timeline): Retrieve the ordered change history for a specific entity, including SEI resolution status.
Get entity churn count (heddle_entity_churn_count_get / churn): Get per-entity change-event counts over an optional time window; never-observed entities return 0 rather than an error.
Get impact radius (heddle_impact_radius_get / blast_radius): Identify downstream-affected entities from stored dated snapshots, with mandatory completeness and staleness indicators; reports NO_SNAPSHOT honestly when edge data is missing.
Get reverify worklist (heddle_reverify_worklist_get / reverify): Generate an agent worklist of entities that must be re-checked before claiming a change is complete.
Capture edge snapshot (heddle_edge_snapshot_capture / capture_snapshot): The only mutating operation — captures dated Loomweave call-graph edges into local .weft/heddle/ storage; supports full or changed_only modes, dry-run, idempotency keys, and staleness guards.
Key characteristics:
All tools return a consistent envelope with schema, ok, data, warnings, next_actions, enrichment, and meta fields, adhering to a frozen warpline.<contract>.v1 schema.
Local-first: all state stored under .weft/heddle/ (git-ignored), without modifying sibling repositories.
Each tool has both an endorsed long name (e.g. heddle_change_list) and a short alias (e.g. changed) returning identical schemas.
Git history can be backfilled via warpline backfill, and freshness maintained through post-commit hooks.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@heddle list changed entities in HEAD~1..HEAD"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Version 1.1.1 · Weft federation member (5th) · local-first · enrich-only
warpline is the Weft federation's temporal / change-impact authority. It owns the one thing no other member stores — per-entity change history across runs, keyed on SEI — and the downstream-propagation query over it. It answers, every session, the question an agent asks before claiming a change is done:
Given this diff: which entities changed, by whom, when — what is downstream-affected over the call graph, and what must I re-verify?
The federation split is deliberate: loomweave owns "now" (the point-in-time graph and SEI minting); warpline owns "over time" (dated change facts and edge snapshots). warpline is enrich-only — it boots, ingests, and answers with no sibling installed.
warpline is advisory only. It never gates a change, never enforces a policy, and never decides whether a change is allowed. This is deconfliction tooling, not security. A warpline answer is an enhancement you can act on or ignore — never a verdict you must clear. It consumes Loomweave SEI (it never mints identity) and feeds advisory change-impact facts to governance-style surfaces such as Legis/Plainweave, which run their own policy; warpline supplies the facts and never makes the call.
The product front door lives at
warpline.foundryside.dev; the reference docs
are under docs/.
6 MCP tools for change lists, entity timelines, churn counts, impact
radius, reverify worklists, and dated edge-snapshot capture — each with a
frozen warpline.<contract>.v1 schema.
Honest answers: every response carries completeness + staleness and a
CLOSED enrichment vocabulary (present | absent | unavailable). Sibling
absence is explicit, never an implied "clean/allowed" state.
Local-first & safe: all state lives under .weft/warpline/ (git-ignored);
the only mutating tool writes there and never touches a sibling repo.
Real SEI resolution against the live loomweave, deployment-independent.
Federation member lifecycle: warpline install / warpline doctor [--fix]
wire and verify MCP bindings, hooks, the agent skill, and config.
Endorsed names + short shims: e.g. warpline_change_list and changed
return identical schema and data.
Related MCP server: SYKE
Install as a uv tool (recommended — provides the
warpline and warpline-mcp executables on your PATH):
uv tool install warpline
warpline --version # warpline 1.1.1Or with pip (warpline is a zero-dependency package):
pip install warplineFor development from a checkout:
git clone <repo-url> warpline && cd warpline
uv run warpline --versionRequires Python ≥ 3.12.
warpline install wires warpline as a federation member of the target repo —
idempotent, atomic, and it never clobbers a sibling's config block:
warpline install --repo /path/to/project # MCP bindings, hooks, skill, config
warpline doctor --repo /path/to/project # verify; add --fix to autofixdoctor exits non-zero if anything is missing and prints a per-component
report (--json emits a warpline.doctor.v1 summary).
warpline backfill --repo /path/to/project --json # ingest git history
warpline changed --repo /path/to/project --rev-range HEAD~1..HEAD --json
warpline capture-snapshot --repo /path/to/project --json # capture loomweave edges
warpline reverify --repo /path/to/project --changed-entity-key-id 1 --jsonThe post-commit hook installed in step 1 keeps the temporal store fresh as you
commit, so changed/timeline/churn answer without a manual backfill.
tools/list — discover the surface (read/write posture, idempotency, repo
requirement, touched paths, federation dependencies).
warpline_change_list (changed) — call first; read its next_actions.
warpline_reverify_worklist_get (reverify) — the worklist to recheck.
warpline_impact_radius_get / warpline_entity_timeline_get — for explanation.
warpline_edge_snapshot_capture (capture_snapshot) — when impact/reverify
reports NO_SNAPSHOT and loomweave is available.
Endorsed name and short shim are interchangeable and return identical schema + data.
Endorsed name | Shim | Schema | Role |
|
|
| Changed entities for a rev range; hands back ready-to-call next actions. |
|
|
| Ordered change history for one entity; reports |
|
|
| Per-entity change-event counts; a never-observed entity is |
|
|
| Downstream affected set with mandatory |
|
|
| The agent worklist to recheck before claiming completion. |
|
|
| The only mutating tool; captures dated loomweave edges into |
Every outbound tool returns the frozen success envelope:
{
"schema": "warpline.<contract>.v1",
"ok": true,
"query": { "repo": "...", "tool": "...", "arguments": {}, "sort": {}, "page": {} },
"data": { },
"warnings": [],
"next_actions": {},
"enrichment": {"sei": "...", "edges": "...", "work": "...",
"risk": "...", "governance": "...", "requirements": "..."},
"meta": {"producer": {"tool": "warpline", "version": "1.1.1"},
"local_only": true, "peer_side_effects": []}
}enrichment is a CLOSED vocab: present (peer present, fact attached),
absent (peer present, no fact), unavailable (peer unreachable) — plus
stale | partial | skipped for edges. None of these is ever a transport
error or an implied clean state.
Errors use warpline.error.v1 with a CLOSED error_code set and retryability
of retry_safe | retry_with_changes | fatal. Switch on error_code, not
message text.
Every entity carries both locator and sei (loomweave:eid:..., opaque —
warpline never mints or parses it). warpline_entity_key_id is internal and not
a federation key; key on sei (preferred) or locator.
Full contract: docs/federation/contracts.md
and the bundled warpline-workflow skill
(src/warpline/skills/warpline-workflow/).
warpline install installs everything by default, or a subset via flags
(--claude-code, --codex, --claude-md, --agents-md, --gitignore,
--hooks, --session-hook, --skills, --codex-skills, --config):
Component | What it does |
MCP bindings | Registers warpline in |
Hooks | git |
Skill | Copies |
Instructions | Injects a |
Config | Writes |
warpline doctor checks all of the above; warpline doctor --fix re-applies
anything fixable.
warpline is local-first; runtime state lives under .weft/warpline/ and is
git-ignored:
.weft/warpline/
├── warpline.db # SQLite temporal store (change events, edge snapshots)
├── config.json # member identity {prefix, name, version}
├── INSTALL_VERSION # schema/version marker
└── .gitignore # keeps ephemeral runtime files out of commitsThe loomweave command warpline uses for SEI resolution / edge capture is
server/project config — set WARPLINE_LOOMWEAVE_COMMAND (default loomweave); it
is not a public MCP tool argument. git add -A never stages a warpline DB.
Filigree work-state enrichment uses filigree's dashboard HTTP API when a reverify
request sets include_federation=true. Set FILIGREE_API_URL to point warpline
at a non-default dashboard; the default is http://localhost:8724. If the
dashboard is absent or unreachable, warpline reports work enrichment as
unavailable / member unreachable and still returns the local worklist.
uv run ruff check . # lint
uv run mypy # strict type-check
uv run pytest # test suite
uv run warpline mcp-smoke --repo . --json # live stdio MCP smoke
uv run warpline dogfood-eval --real-member-repo /path/to/member-repo --jsonwarpline dogfood-eval exercises the real change → reverify loop (synthetic lanes
plus a real-member lane against an actual loomweave index) and gates on
ready=True. See spike/REPORT.md for the readiness verdict
and CHANGELOG.md for release history.
Topic | Where |
Docs site landing / table of contents | |
Getting started (install → first worklist) | |
Concepts (mental model, advisory-not-gating, degrade) | |
CLI reference (every command, flag, exit code) | |
MCP tool reference (all 6 frozen tools) | |
Federation (seams, what it feeds/consumes, degrade) | |
Federation seam contracts (frozen, internal) | |
Agent usage (progressive-disclosure skill) | |
Solution architecture (internal) | |
Product workspace (vision, roadmap, PDRs) | |
Release history |
The authoritative interface-lock specification is hub-owned
(2026-06-13-warpline-interface-lock.md in the weft hub); warpline implements to
it and does not edit it.
warpline implements to a frozen cross-member contract. Changes to a tool's name,
input/output schema, the envelope, or the error/enrichment vocabularies are a
hub decision — escalate with evidence rather than diverging. Internal changes
must keep ruff, mypy --strict, and the full test suite green, and the 14
golden vectors (tests/contracts/test_golden_vectors.py) passing.
See CONTRIBUTING.md for the full workflow and
CODE_OF_CONDUCT.md for community expectations.
MIT — see LICENSE. Copyright (c) 2026 John Morrissey. Consistent
with the rest of the Weft federation.
Downstream affected entities from stored dated snapshots, with mandatory completeness+staleness. NO_SNAPSHOT is an honest changed-set-only answer.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| rev_range | No | ||
| changed_refs | No | ||
| changed_entity_key_ids | No | ||
| depth | No | ||
| filters | No | ||
| sort_by | No | ||
| sort_order | No | ||
| limit | No | ||
| cursor | No |
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| ok | Yes | |
| query | Yes | |
| data | Yes | |
| warnings | Yes | |
| next_actions | Yes | |
| enrichment | Yes | |
| meta | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must disclose behavior. It hints at 'mandatory completeness+staleness' and 'NO_SNAPSHOT' being an honest answer, but does not explain what these mean or whether the tool is read-only, destructive, etc. Lacks essential behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely terse (2 sentences), but sacrifices clarity. Important information about behavior and parameters is omitted. Not efficient; it's under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 params, nested objects, no schema descriptions, many siblings), the description fails to provide enough context for an agent to understand or use the tool correctly. Completely inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with 10 parameters including complex nested objects. The description provides no explanations for any parameters (e.g., repo, rev_range, changed_refs, filters). Adding zero value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it finds 'downstream affected entities from stored dated snapshots' but uses vague jargon like 'mandatory completeness+staleness' and 'NO_SNAPSHOT', making the purpose unclear. It does not effectively differentiate from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus its many siblings (e.g., changed, heddle_impact_radius_get). No context about prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture dated loomweave edges into heddle's local store. Mutates ONLY .weft/heddle state; never a sibling repo. loomweave command is server config.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| commit | No | ||
| mode | No | ||
| changed_refs | No | ||
| if_stale_after | No | ||
| max_entities | No | ||
| dry_run | No | ||
| idempotency_key | No |
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| ok | Yes | |
| query | Yes | |
| data | Yes | |
| warnings | Yes | |
| next_actions | Yes | |
| enrichment | Yes | |
| meta | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It mentions mutation scope and server config, but fails to disclose destructive potential, idempotency, or safety profiles like dry-run or idempotency_key. This is insufficient for an 8-parameter tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences efficiently convey the core purpose and scope without extraneous words. Could be slightly more structured, but it remains concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high parameter count (8), zero schema coverage, and no annotations, the description is severely incomplete. It lacks explanations of behavior under different modes, error states, side effects, and parameter interactions, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanations for any of the 8 parameters. The description adds zero value beyond the raw schema, leaving the agent without guidance on how to fill fields like repo, mode, or changed_refs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: capturing dated loomweave edges into heddle's local store. It also distinguishes from siblings by noting it mutates only .weft/heddle state and never a sibling repo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for local state mutation without affecting siblings, but it does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List changed entities for an ingested repo and get the ready-to-call reverify/impact next actions. Local-only; may initialize .weft/heddle state.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| rev_range | No | ||
| base_ref | No | ||
| head_ref | No | ||
| filters | No | ||
| sort_by | No | ||
| sort_order | No | ||
| limit | No | ||
| cursor | No | ||
| include_next_actions | No |
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| ok | Yes | |
| query | Yes | |
| data | Yes | |
| warnings | Yes | |
| next_actions | Yes | |
| enrichment | Yes | |
| meta | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description partially compensates by disclosing that it is local-only and may initialize state. However, it does not detail other behavioral traits such as permissions, side effects beyond initialization, or response format. More transparency is needed given the lack of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences that front-load the purpose. Every sentence adds value without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 parameters, output schema), the description is incomplete. It lacks parameter details, output structure, and comprehensive behavior. It does not fully inform an AI agent about how to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 10 parameters with 0% description coverage, and the description does not explain any parameters. It fails to add semantic meaning beyond parameter names. The description must compensate for low schema coverage but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists changed entities and retrieves next actions for reverify/impact. It identifies the resource (changed entities for an ingested repo) and the action (list and get next actions). It hints at differentiation from siblings like 'heddle_change_list' by mentioning 'ready-to-call reverify/impact next actions', but could be more explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context ('Local-only; may initialize .weft/heddle state') but does not explicitly state when to use this tool versus alternatives like 'heddle_reverify_worklist_get' or 'reverify'. Usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-entity change-event count over an optional window (SEIs preferred). A never-observed entity returns churn_count 0, not an error.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| entity_refs | Yes | ||
| window | No | ||
| sort_by | No | ||
| sort_order | No | ||
| limit | No | ||
| cursor | No |
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| ok | Yes | |
| query | Yes | |
| data | Yes | |
| warnings | Yes | |
| next_actions | Yes | |
| enrichment | Yes | |
| meta | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that never-observed entities return 0, not an error, which is valuable. But it does not mention mutability, auth needs, rate limits, or specifics about the window parameter. Since annotations are absent, the description carries full burden and is only partially adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-loaded with purpose. No wasted words, but could be expanded with important details without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters including a nested object, cursor, and sort fields, the description is insufficient. It fails to explain what 'SEIs' means, how the window parameter is structured, sort options, or pagination behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds no parameter-specific information beyond the general purpose. It mentions 'window' but does not explain its structure or the other 5 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it counts change events per entity over an optional window and handles never-observed entities. However, it does not differentiate from similar siblings like 'changed' or 'heddle_entity_churn_count_get'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No mention of prerequisites, exclusions, or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List changed entities for an ingested repo and get the ready-to-call reverify/impact next actions. Local-only; may initialize .weft/heddle state.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| rev_range | No | ||
| base_ref | No | ||
| head_ref | No | ||
| filters | No | ||
| sort_by | No | ||
| sort_order | No | ||
| limit | No | ||
| cursor | No | ||
| include_next_actions | No |
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| ok | Yes | |
| query | Yes | |
| data | Yes | |
| warnings | Yes | |
| next_actions | Yes | |
| enrichment | Yes | |
| meta | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden. It mentions 'Local-only; may initialize .weft/heddle state' which is a behavioral trait. However, it does not disclose potential side effects like file writes or modifications, nor does it clarify what 'initialize' entails. More detail would be needed for a higher score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first states the main action clearly, second adds important caveats (local-only, may initialize state). No unnecessary words, front-loaded, and efficiently conveys scope and constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite high complexity (10 params, nested objects, output schema), the description is minimal. It does not explain the parameters, output structure, pagination (cursor, limit), or sorting. The output schema exists but is not referenced. The description is insufficient for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 10 parameters. It says nothing about 'repo', 'rev_range', 'filters', etc. This fails to add meaning beyond the schema, leaving the agent guessing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists changed entities and provides next actions like reverify/impact. It distinguishes itself from siblings like 'changed' by mentioning reverify/impact next actions. However, it does not explicitly differentiate from other similar tools like 'heddle_reverify_worklist_get' or 'heddle_entity_churn_count_get', so it is not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to list changed entities and get next actions, but it does not specify when not to use it or provide alternatives among sibling tools. The context signal shows many heddle-related siblings, yet no guidance is given on choosing this over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture dated loomweave edges into heddle's local store. Mutates ONLY .weft/heddle state; never a sibling repo. loomweave command is server config.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| commit | No | ||
| mode | No | ||
| changed_refs | No | ||
| if_stale_after | No | ||
| max_entities | No | ||
| dry_run | No | ||
| idempotency_key | No |
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| ok | Yes | |
| query | Yes | |
| data | Yes | |
| warnings | Yes | |
| next_actions | Yes | |
| enrichment | Yes | |
| meta | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that mutations are scoped to .weft/heddle state and mentions a server config for the loomweave command, but does not address idempotency, side effects, dry_run behavior, or other behavioral traits beyond the basic mutation claim.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, directly stating purpose and a key constraint. No redundant information, but a slightly more structured format (e.g., bullet points for key behaviors) could improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no annotations, and an output schema (unseen), the description is insufficient. It does not explain parameter usage, return values, or provide enough context for an agent to correctly invoke the tool without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameters are described in the schema. The description adds no information about parameters; it only mentions capturing edges without relating to any of the 8 parameters defined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool captures 'dated loomweave edges' into a specific store and distinguishes from sibling tools by noting it only mutates .weft/heddle state. However, the term 'loomweave edges' is domain-specific and may be unclear to some agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description mentions that the tool never mutates a sibling repo, providing a hint about when not to use it, but it lacks explicit guidance on when to use this tool versus alternatives like 'capture_snapshot' or 'heddle_change_list'. No explicit when/when-not or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-entity change-event count over an optional window (SEIs preferred). A never-observed entity returns churn_count 0, not an error.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| entity_refs | Yes | ||
| window | No | ||
| sort_by | No | ||
| sort_order | No | ||
| limit | No | ||
| cursor | No |
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| ok | Yes | |
| query | Yes | |
| data | Yes | |
| warnings | Yes | |
| next_actions | Yes | |
| enrichment | Yes | |
| meta | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description adds value by clarifying return value for unseen entities (0 not error). However, it lacks disclosure on idempotency, permissions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose and a key behavioral trait. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is too minimal for a complex tool with 7 parameters, nested objects, and many siblings. Missing guidance on sorting, pagination, and how entity_refs is constructed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 7 parameters with 0% description coverage. The description only mentions 'optional window' without explaining any parameter structure or constraints, leaving the agent with no additional meaning beyond schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a per-entity change-event count with an optional window. It specifies a behavior for never-observed entities, but does not differentiate from sibling tools like 'churn' or 'heddle_change_list'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No context on prerequisites or limitations beyond the brief behavior note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ordered change history for one entity ref. heddle reports only whether it resolved a SEI (sei_resolution); it never claims lineage.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| entity_ref | No | ||
| entity | No | ||
| filters | No | ||
| sort_by | No | ||
| sort_order | No | ||
| limit | No | ||
| cursor | No |
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| ok | Yes | |
| query | Yes | |
| data | Yes | |
| warnings | Yes | |
| next_actions | Yes | |
| enrichment | Yes | |
| meta | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description carries full burden. It discloses a key behavioral trait: it only reports SEI resolution and never claims lineage. However, it does not mention whether the operation is read-only, requires authentication, has rate limits, or how pagination works.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the purpose. No filler, but could be slightly more structured (e.g., listing key constraints).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the tool is complex with 8 params including nested objects. The description fails to explain parameters or usage context, making it incomplete for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with 8 parameters. Description only mentions 'entity ref' but does not explain any parameter's purpose, format, or constraints. This severely hinders correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it provides 'ordered change history for one entity ref' – a specific verb and resource. Differentiates from sibling tools like 'timeline' and 'heddle_change_list' by focusing on a single entity with ordering and specific SEI resolution reporting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus siblings. The description only adds a behavioral note about SEI resolution and lineage, but does not indicate prerequisites, constraints, or alternative scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Downstream affected entities from stored dated snapshots, with mandatory completeness+staleness. NO_SNAPSHOT is an honest changed-set-only answer.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| rev_range | No | ||
| changed_refs | No | ||
| changed_entity_key_ids | No | ||
| depth | No | ||
| filters | No | ||
| sort_by | No | ||
| sort_order | No | ||
| limit | No | ||
| cursor | No |
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| ok | Yes | |
| query | Yes | |
| data | Yes | |
| warnings | Yes | |
| next_actions | Yes | |
| enrichment | Yes | |
| meta | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It hints at two modes (normal and NO_SNAPSHOT) and mentions 'completeness+staleness', but lacks details on side effects, authorization requirements, rate limits, or output characteristics. It does not clarify if the tool is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and uses no fluff, but it is overly terse and includes jargon ('downstream affected entities', 'changed-set-only answer') that may confuse. It front-loads the core concept but lacks clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 parameters, nested objects, output schema), the description is severely insufficient. It does not explain parameters, output format, or how to switch between modes. It fails to provide a complete understanding of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It provides no information about any of the 10 parameters (repo, rev_range, etc.) or how to use them. The description only mentions high-level output modes without linking to parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description mentions 'Downstream affected entities from stored dated snapshots' which gives a general idea of what the tool does, but lacks a clear verb and does not distinguish from siblings like 'blast_radius' or 'changed'. The term 'downstream affected entities' is vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like 'blast_radius' or 'heddle_change_list'. It mentions 'mandatory completeness+staleness' and 'NO_SNAPSHOT' mode, but does not explain the context or when each mode is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render the agent worklist to recheck before claiming completion. Sibling enrichment is advisory and never gates; absence is explicit, never clean.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| rev_range | No | ||
| changed_refs | No | ||
| changed_entity_key_ids | No | ||
| depth | No | ||
| filters | No | ||
| sort_by | No | ||
| sort_order | No | ||
| group_by | No | ||
| limit | No | ||
| cursor | No | ||
| include_federation | No |
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| ok | Yes | |
| query | Yes | |
| data | Yes | |
| warnings | Yes | |
| next_actions | Yes | |
| enrichment | Yes | |
| meta | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. While it mentions that sibling enrichment is optional and absence is explicit, it fails to state side effects, idempotency, authentication needs, or rate limits. The cryptic second sentence adds limited value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) but the second sentence is cryptic and may confuse rather than clarify. It could be restructured to front-load practical usage information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 params, many siblings, output schema), the description is incomplete. It does not explain the output, how the worklist relates to other heddle tools, or how to use parameters effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 12 parameters with 0% description coverage in the schema, yet the description provides no explanation for any parameter. It does not mention 'repo', 'rev_range', or others, leaving the AI agent to guess their meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Render the agent worklist to recheck before claiming completion', which clearly identifies the tool's purpose: retrieving a worklist for verification. However, it does not differentiate from sibling tools like 'reverify' or others, and the term 'agent worklist' is not further clarified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It only states an internal behavioral property ('Sibling enrichment is advisory and never gates'), but offers no explicit when/when-not instructions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render the agent worklist to recheck before claiming completion. Sibling enrichment is advisory and never gates; absence is explicit, never clean.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| rev_range | No | ||
| changed_refs | No | ||
| changed_entity_key_ids | No | ||
| depth | No | ||
| filters | No | ||
| sort_by | No | ||
| sort_order | No | ||
| group_by | No | ||
| limit | No | ||
| cursor | No | ||
| include_federation | No |
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| ok | Yes | |
| query | Yes | |
| data | Yes | |
| warnings | Yes | |
| next_actions | Yes | |
| enrichment | Yes | |
| meta | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must disclose behavioral traits. The cryptic phrase 'sibling enrichment is advisory and never gates; absence is explicit, never clean' provides unclear behavioral context. No mention of mutation, side effects, or authorization.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences), but the second sentence is confusing and adds little value. It is concise but not well-structured for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 parameters, nested objects, output schema, many siblings), the description is far too brief. It lacks parameter explanations, usage context, output description, and integration with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about any of the 12 parameters. This is a critical gap for an agent to invoke the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it renders the agent worklist to recheck before claiming completion, but 'agent worklist' is undefined and there is no distinction from sibling tools like 'heddle_reverify_worklist_get'. The cryptic second sentence does not clarify the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus sibling tools or when not to use it. The description does not address alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ordered change history for one entity ref. heddle reports only whether it resolved a SEI (sei_resolution); it never claims lineage.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| entity_ref | No | ||
| entity | No | ||
| filters | No | ||
| sort_by | No | ||
| sort_order | No | ||
| limit | No | ||
| cursor | No |
| Name | Required | Description |
|---|---|---|
| schema | Yes | |
| ok | Yes | |
| query | Yes | |
| data | Yes | |
| warnings | Yes | |
| next_actions | Yes | |
| enrichment | Yes | |
| meta | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool only reports SEI resolution and not lineage, but it fails to mention ordering criteria, authentication needs, destructive potential, or pagination behavior. The lack of detail leaves significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise and front-loaded with the primary purpose. However, it omits essential information about parameters and usage, making it too sparse. Conciseness is achieved at the cost of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters (many nested) and a rich set of sibling tools, the description is inadequate. It does not explain entity_ref structure, filter semantics, sorting options, or pagination. The presence of an output schema does not compensate for the lack of input guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description should explain parameters but does not. No parameter names or usage are mentioned. The only clue is 'for one entity ref' hinting at entity_ref, but repo, filters, sort, limit, cursor remain unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Ordered change history for one entity ref,' which clearly indicates the tool provides a chronological list of changes for a single entity. It further distinguishes from siblings by noting that it only reports SEI resolution and never claims lineage, differentiating it from tools like blast_radius or heddle_impact_radius_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The phrase 'for one entity ref' implies single-entity use, but there is no mention of when not to use it or which sibling tools are better suited for multi-entity or lineage queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0blast_radiuscapture_snapshotchangedchurnheddle_change_listheddle_edge_snapshot_captureheddle_entity_churn_count_getheddle_entity_timeline_getheddle_impact_radius_getheddle_reverify_worklist_getreverifytimelineThe tool set contains exact duplicates (e.g., changed and heddle_change_list, churn and heddle_entity_churn_count_get, etc.) with identical descriptions, making it impossible for an agent to distinguish between them. This severe overlap undermines any ability to reliably select the correct tool.
Naming is chaotic: half the tools use short names (blast_radius, changed, churn, reverify, timeline) while the other half use a 'heddle_' prefix with different patterns (heddle_change_list, heddle_edge_snapshot_capture, etc.). Verbs are mixed (capture, changed, get) and no consistent verb_noun pattern is followed.
The raw count of 12 tools is within a reasonable range, but half are duplicates, effectively reducing the unique tool count to 6. While not extreme, the duplication suggests poor scoping and undermines efficiency.
The set covers core operations like capturing snapshots, listing changes, getting churn/timeline/impact radius, but lacks update/delete or other lifecycle operations. The duplicates do not add new functionality, so coverage is adequate but not comprehensive.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for Product Management
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Append-only decisions with provenance, supersession, retrieval, and audited MCP actions.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/foundryside-dev/warpline'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
