Tool Reference

The ATOMS MCP Server exposes 16 tools that let AI assistants manage requirements, test cases, and traceability data. Tools are organized into three categories: Entry Points, Read Tools, and Write Tools.

Every tool response follows a consistent format. See Response Format below.

Entry Points

Start here. These tools help you connect and discover your projects.

Tool	Description	App
`atoms_status`	Health check and authentication status. Works without authentication.	No
`atoms_list_projects`	Discover all accessible projects. Call this first to get project IDs.	No

Read Tools

Query, search, and analyze your requirements data. All read tools require a project_id obtained from atoms_list_projects.

Tool	Description	App
`atoms_list_items`	Browse items with optional type, domain, and level filters. Supports pagination.	No
`atoms_get_item`	Get full details of a single item including relationships and test history.	No
`atoms_search`	Full-text search across all items in a project.	No
`atoms_get_coverage`	Find requirements without linked test cases (coverage gaps).	Yes
`atoms_get_history`	Audit trail for an item showing who changed what, and when.	No
`atoms_export_mermaid`	Generate a Mermaid diagram of the requirement/test hierarchy.	Yes
`atoms_trace`	Walk the traceability graph upstream, downstream, or both from a starting item.	Yes
`atoms_project_summary`	One-call project health and compliance dashboard.	Yes

Write Tools

Create, update, and manage items and relationships. All write tools require a project_id.

Tool	Description	App
`atoms_create_item`	Create a new requirement, test case, or note.	No
`atoms_update_item`	Partial update of an existing item. Only provided fields are changed.	No
`atoms_delete_item`	Soft-delete an item (sets `deleted_at`, preserves for audit trail).	No
`atoms_link_items`	Add or remove relationships between items (parent, child, related, verifies).	No
`atoms_bulk_import`	Batch create 1--100 items in a single call.	Yes
`atoms_record_test_result`	Record a pass/fail/blocked result for a test case.	No

Response Format

All tools return a consistent JSON envelope:

Success

{
  "status": "success",
  "data": { ... },
  "meta": {
    "total_count": 42,
    "page_size": 50,
    "page_number": 1
  }
}

The meta field is included when the response is paginated. Not all tools return meta.

Error

{
  "status": "error",
  "message": "Project not found",
  "next_steps": [
    "Verify the project_id is correct by calling atoms_list_projects",
    "Check that you have access to this project"
  ]
}

If you receive authentication errors, call atoms_status first to verify your connection and token validity.

Interactive Apps

Five tools include an App -- an interactive UI that renders inside supported MCP hosts (like Claude Desktop). These are marked with "Yes" in the App column above. In hosts that do not support MCP Apps, the tools still return structured JSON data.

Tool Reference

On this page