Agent Tools

When you chat with ARK CLI, you don't call these tools directly. The AI agent decides which tools to use based on your questions. Understanding the available tools helps you ask better questions and interpret the agent's reasoning.

listAvailableGraphs

Purpose: Lists all available knowledge graphs with their metadata.

Parameters: None.

Returns: Array of graph metadata objects, each containing id, name, description, category, and shortDescription.

The agent uses this tool when it needs to know which graphs are available or when you ask about the available data. This is typically one of the first tools called when the agent is unsure which graph to query.

Example triggers: "What graphs do you have?", "What data is available?", "Which knowledge bases can I explore?"

---

findNodesByName

Purpose: Search for nodes by name using partial, case-insensitive matching.

Parameters:

Returns: Up to 10 matching nodes, each with id, name, type, knowledgeGraphId, and properties.

This is the primary entry point for exploring a graph. The agent uses it to locate entities you mention in your questions. Searching for "alzheimer" will match "Alzheimer's disease", "Alzheimer disease", etc.

Example triggers: "Tell me about BRCA1", "Find metformin in the graph", "What do you know about Type 2 Diabetes?"

---

getNodeDetails

Purpose: Get detailed information about a specific node by its ID.

Parameters:

Returns: Full node record including id, name, type, knowledgeGraphId, knowledgeGraphName, and all properties.

After finding a node with findNodesByName, the agent often calls this tool to get the complete property set. This is rendered in the terminal as a structured block showing the node's name, type, graph, and a formatted property list.

Example triggers: Used internally after finding nodes. Typically not triggered directly by user queries.

---

getNeighborsByNodeId

Purpose: Get the IDs of all nodes connected to a given node, optionally filtered by edge type.

Parameters:

Returns: Array of neighbor node ID strings.

This is the core graph traversal tool. The agent uses it to explore relationships, such as finding which drugs treat a disease or which genes are associated with a condition. The optional edgeType filter lets the agent focus on specific relationship types.

Example triggers: "What drugs treat Alzheimer's?", "What genes are associated with this disease?", "Show me the neighbors of BRCA1"

---

searchInSurroundings

Purpose: Search within 1-2 hops of a given node with optional filters for node type, edge type, and keyword matching.

Parameters:

Returns: An object with mainNode (the starting node) and neighbors (array of matching nodes with relationship information).

This is the most powerful traversal tool. It enables multi-hop reasoning, such as finding all genes in a disease's neighborhood that match a specific keyword. For k=1, each neighbor includes edgesToCandidate and edgesFromCandidate arrays showing how it connects to the main node.

The query parameter performs keyword matching: it first checks node names (case-insensitive substring), then searches node properties for individual query words (after stopword removal), ranking results by relevance.

Example triggers: "Are there any kinase-related proteins near BRCA1?", "Find diseases connected to this gene within 2 hops", "What pathways are in the neighborhood of metformin?"

---

How the Agent Chooses Tools

The agent follows a general pattern when answering questions:

1. findNodesByName: Locate the entity you asked about by searching for it in the graph.
2. getNodeDetails: Get full properties if more information about that entity is needed.
3. getNeighborsByNodeId: Explore direct relationships (1-hop traversal).
4. searchInSurroundings: Perform filtered, multi-hop queries when direct traversal isn't enough.

For complex questions, the agent chains multiple tool calls. For example, to answer "Is there a gene that connects disease A and biological process B?", the agent might:

1. findNodesByName for disease A
2. findNodesByName for biological process B
3. searchInSurroundings on disease A with a query matching B
4. getNodeDetails on candidate connecting genes