Spec tools

Read, search and change the elements of the requirements model. This group has 22 tools, 1 of them available only with spec-editor Pro.

Tool	Edition	Summary
add_relationship	Open core	Add a relationship between elements.
allocate_id	Open core	Reserve and return the next free id for a prefix (e.g.
code_bindings	Open core	An element’s implements code bindings (path, line, symbol, language, revision, drift); a MOD aggregates its children.
confirm_relationship	Open core	Confirm a relationship, clearing its suspect-link state: re-takes both endpoints’ content snapshots, refreshes linked_at, and records confirmed_by/confirmed_at.
coverage_divergence	Open core	Model/code divergence sections of the coverage report.
delete_element	Open core	Delete an element by ID.
element_attributes	Open core	Attributes of specific elements — the part list_all_elements deliberately leaves out.
element_view	Open core	One element’s view along the time (design-time/run-time) x media (text/image/dynamic) axes, in one call.
find_related	Open core	Find elements related to the specified one.
get_context_for_file	Pro	Build specification context for a code file.
get_lineage	Open core	Full transitive ancestor/descendant lineage of an element, grouped by direction and relationship type.
get_methodology	Open core	Get the methodology description.
list_all_elements	Open core	List all project elements with optional pagination.
list_aspect	Open core	List all elements of an aspect with optional pagination.
read_element	Open core	Read an element by ID.
remove_relationship	Open core	Remove a relationship.
run_metrics	Open core	Compute connectivity metrics.
run_validate	Open core	Run MCP specification validation.
search_elements	Open core	Full-text search by ID, title, and content with optional pagination.
tree	Open core	Permanent left-hand element tree, one call: every aspect’s parent/child hierarchy with a per-node element count.
write_element	Open core	Create or update an element.
write_elements	Open core	Write a list of elements in one call (each item takes the write_element arguments); the index is updated incrementally.

add_relationship

Add a relationship between elements.

Parameters

Parameter	Type	Required	Description
rel_type	string	yes	Relationship type
role	string	no	Role in the relationship
source_id	string	yes	Source element ID
target_id	string	yes	Target element ID

allocate_id

Reserve and return the next free id for a prefix (e.g. ‘MOD’, ‘REQ’), without writing an element. Use when you need the id before creating the element (e.g. to reference it from a sibling in the same turn) instead of guessing ‘max + 1’ yourself.

Parameters

Parameter	Type	Required	Description
prefix	string	yes	Id prefix, e.g. ‘MOD’

code_bindings

An element’s implements code bindings (path, line, symbol, language, revision, drift); a MOD aggregates its children.

Parameters

Parameter	Type	Required	Description
element_id	string	yes	Element ID

confirm_relationship

Confirm a relationship, clearing its suspect-link state: re-takes both endpoints’ content snapshots, refreshes linked_at, and records confirmed_by/confirmed_at.

Parameters

Parameter	Type	Required	Description
confirmed_by	string	yes	Confirming user’s identity
rel_type	string	yes
source_id	string	yes
target_id	string	yes

coverage_divergence

Model/code divergence sections of the coverage report.

Parameters

This tool takes no parameters.

delete_element

Delete an element by ID. Pass force=true to bypass SRC protection.

Parameters

Parameter	Type	Required	Description
element_id	string	yes	Element ID
force	boolean	no	Bypass SRC deletion protection (VSCode UI uses this)

element_attributes

Attributes of specific elements — the part list_all_elements deliberately leaves out. Returns {attributes: {id: {…}}, count, missing}. Pass the ids you need; omitting element_ids returns every element’s attributes and is as heavy as it sounds.

Parameters

Parameter	Type	Required	Description
element_ids	array of string	no	Element ids to fetch attributes for (omit for all elements)

element_view

One element’s view along the time (design-time/run-time) x media (text/image/dynamic) axes, in one call. Combinations with no data return {available: false, reason} instead of an error.

Parameters

Parameter	Type	Required	Description
element_id	string	yes	Element ID.
media	string	no	One of: [‘text’, ‘image’, ‘dynamic’]. Default ‘text’.
project_path	string	yes	Path to spec-editor project (directory with methodology.yaml)
time	string	no	One of: [‘design-time’, ‘run-time’]. Default ‘design-time’.
window	string	no	Relative span for the run-time axis, e.g. ‘24h’, ‘7d’, ‘4w’. Default ‘24h’.

find_related

Find elements related to the specified one.

Parameters

Parameter	Type	Required	Description
element_id	string	yes	Element ID

get_context_for_file

Pro tool. Available with the spec-editor Pro plugin.

Build specification context for a code file. Parses implements annotations and loads referenced requirements with related elements.

Parameters

Parameter	Type	Required	Description
file_path	string	yes	Path to the code file

get_lineage

Full transitive ancestor/descendant lineage of an element, grouped by direction and relationship type.

Parameters

Parameter	Type	Required	Description
element_id	string	yes	Element ID

get_methodology

Get the methodology description.

Parameters

This tool takes no parameters.

list_all_elements

List all project elements with optional pagination. Summary fields only (id, aspect, element_type, title, status, parent, children, relationships, derived_from, covered_by, tags) — element attributes are NOT included; get them from element_attributes.

Parameters

Parameter	Type	Required	Description
fields	string	no	‘tree’ — only id, title, status, element_type, aspect, parent, children, is_unlinked, has_suspect_relationships (no relationships, tags, covered_by, derived_from). Omit for the full summary
limit	integer	no	Max results to return (default 0 = all)
offset	integer	no	Number of results to skip (default 0)
unlinked_only	boolean	no	Only return elements with no incoming or outgoing relationships (default false)

list_aspect

List all elements of an aspect with optional pagination.

Parameters

Parameter	Type	Required	Description
aspect_name	string	yes	Aspect name
limit	integer	no	Max results to return (default 0 = all)
offset	integer	no	Number of results to skip (default 0)

read_element

Read an element by ID. Use deep=true to also get children, parent, and relationship targets in one call. Returns aspect, element_type, title, status, parent, children, relationships, content.

Parameters

Parameter	Type	Required	Description
deep	boolean	no	If true, also returns children, parent, and relationship targets (full context in one call)
element_id	string	yes	Element ID

remove_relationship

Remove a relationship.

Parameters

Parameter	Type	Required	Description
rel_type	string	yes
source_id	string	yes
target_id	string	yes

run_metrics

Compute connectivity metrics.

Parameters

Parameter	Type	Required	Description
aspect	string	no	Return only this aspect’s dashboard figures (‘*’ = whole model)
host	string	no	Host id for the run figures

run_validate

Run MCP specification validation.

Parameters

This tool takes no parameters.

search_elements

Full-text search by ID, title, and content with optional pagination. Substring match over the model’s own elements only — it never touches the semantic code index; for natural-language search over the codebase use search_semantic instead.

Parameters

Parameter	Type	Required	Description
limit	integer	no	Max results to return (default 0 = all)
offset	integer	no	Number of results to skip (default 0)
query	string	yes	Search query

tree

Permanent left-hand element tree, one call: every aspect’s parent/child hierarchy with a per-node element count. Optionally filter to one aspect and/or one delivery status (one of: [‘blocked’, ‘confirmed’, ‘deprecated’, ‘draft’, ‘fixed’, ‘implemented’, ‘reviewed’]); a filtered-out subtree is pruned entirely rather than shown empty.

Parameters

Parameter	Type	Required	Description
aspect	string	no	Restrict to one aspect’s tree. Omit for all aspects.
project_path	string	yes	Path to spec-editor project (directory with methodology.yaml)
status	string	no	Restrict to elements with this status. One of: [‘blocked’, ‘confirmed’, ‘deprecated’, ‘draft’, ‘fixed’, ‘implemented’, ‘reviewed’].

write_element

Create or update an element.

Parameters

Parameter	Type	Required	Description
aspect	string	yes	Aspect name
attributes	object	no	Type-specific attributes declared by the methodology for this element type; see get_methodology
children	array of string	no	Child element IDs
content	string	no	Markdown description
derived_from	array of string	yes	IDs of source requirements from which the element is derived
element_type	string	yes	Element type
from_actor	string	no	Operator writes only: human:owner when relaying the owner’s instruction (needs note)
id	string	yes	Unique ID
intent	string, one of create, update	yes	create a new element or update an existing one; the answer carries merged=true and the existing id when a create was merged into a same-titled element
note	string	no	Quote of the owner’s instruction (operator writes from human:owner)
parent	string	no	Parent ID (optional)
provenance_source	string	no	Source file of the requirement (for traceability)
status	string	no	draft, reviewed, confirmed, deprecated
tags	array of string	no	Tags
title	string	yes	Element title

write_elements

Write a list of elements in one call (each item takes the write_element arguments); the index is updated incrementally.

Parameters

Parameter	Type	Required	Description
elements	array of object	yes	write_element argument objects