atoms_link_items

Add or remove a directional relationship between two items in the same project. Relationships power the traceability graph used by atoms_trace, atoms_get_coverage, and atoms_export_mermaid.

Parameters

Parameter	Type	Required	Description
`project_id`	`string (UUID)`	Yes	The project containing both items
`from_id`	`string`	Yes	Source item ID, e.g. `"TC-012"`
`to_id`	`string`	Yes	Target item ID, e.g. `"REQ-001"`
`type`	`string`	Yes	Relationship type: `parent`, `child`, `related`, `verifies`, or `verified_by`
`action`	`string`	Yes	`add` to create the link, `remove` to delete it

Example Response

{
  "status": "success",
  "data": {
    "from_id": "TC-012",
    "to_id": "REQ-001",
    "type": "verifies",
    "action": "add",
    "message": "Relationship added: TC-012 verifies REQ-001"
  }
}

Notes

This tool modifies data (readOnlyHint: false, destructiveHint: false, idempotentHint: true).
Relationships are dual-written: stored in the item's JSONB relationships field and in the item_relationships shadow table for efficient graph traversal.
Adding an already-existing relationship is a no-op (idempotent). Removing a non-existent relationship also succeeds silently.
Self-referencing is prevented : from_id and to_id must be different items.
Use verifies / verified_by to link test cases to requirements. This directly affects the coverage percentage reported by atoms_get_coverage.

Parameters

Example Response

Notes

On this page