Tool Reference
atoms_link_items
Add or remove relationships between 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: true,idempotentHint: false). It is marked destructive becauseremovedeletes a relationship, so a client may ask you to approve every call. - Under the Block destructive ops policy of the project's organization,
remove(the top-levelactionand anyoperations[]entry) is refused with "op remove is blocked by org policy", whileaddstill runs.atoms_link_mitigationremoveis refused the same way. - The ATOMS database refuses the same removal too, so a call that reaches it answers "Removing a link is blocked by org policy. This change was not saved.", or, on a project with multi-user saving, names the org's MCP Access Policy for that link. Do not retry it: only an org admin can change the policy.
- Relationships are dual-written: stored in the item's JSONB
relationshipsfield and in theitem_relationshipsshadow table for efficient graph traversal. - Adding an already-existing relationship is a no-op, and removing a non-existent relationship also succeeds silently. The tool is still registered with
idempotentHint: false: aremovedeletes a link, and anoperations[]call is applied one operation at a time, not as one transaction, so a client should not treat a retry as free. - Self-referencing is prevented :
from_idandto_idmust be different items. - Use
verifies/verified_byto link test cases to requirements. This directly affects the coverage percentage reported byatoms_get_coverage.