# How to Use `/v3/tools/list` and `/v3/tools/call` for Knowledge Retrieval in TencentDB Agent Memory

> Master knowledge retrieval in TencentDB Agent Memory. Learn to use /v3/tools/list and /v3/tools/call to discover and fetch information efficiently using the discover-then-use pattern.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-26

---

**The TencentDB Agent Memory platform enables AI agents to perform knowledge retrieval through two HTTP endpoints—`/v3/tools/list` for discovering available tools and `/v3/tools/call` for fetching specific content—implementing a discover-then-use pattern managed by the MemoryKnowledge service.**

The TencentDB-Agent-Memory repository provides a MemoryKnowledge service that exposes RESTful endpoints for programmatic knowledge retrieval. These endpoints allow autonomous agents to dynamically discover available knowledge assets such as Wiki pages, source code files, and impact-path graphs, then retrieve specific content on demand. This architecture decouples capability discovery from content access, enabling flexible agent workflows.

## Understanding the Two-Step Knowledge Retrieval Workflow

The MemoryKnowledge service implements a deliberate **discover-then-use** pattern that mirrors standard LLM agent behaviors. This design separates the metadata catalog from the content delivery layer, allowing agents to make informed decisions about which knowledge sources to query.

### Step 1: Capability Discovery with `/v3/tools/list`

The `POST /v3/tools/list` endpoint serves as the **capability discovery** mechanism. According to the source documentation in [`MemoryKnowledge/v3-api-memoryknowledge-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/v3-api-memoryknowledge-doc.md) at line 511, this endpoint accepts an empty JSON body or optional filters and returns a catalog of all registered "tools" available in the system.

When an agent calls this endpoint, the service returns a JSON array describing each tool with its `name`, `type`, `id`, and associated metadata. As documented in the main [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md) at line 265, this list includes diverse asset types such as Wiki pages, source-code files, and impact-path graphs. The agent uses this metadata to determine which specific knowledge source contains the information required for its task.

### Step 2: Content Retrieval with `/v3/tools/call`

After identifying a relevant tool from the discovery phase, agents use `POST /v3/tools/call` to fetch the actual content. As specified in [`MemoryKnowledge/v3-api-memoryknowledge-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/v3-api-memoryknowledge-doc.md) at line 553, this endpoint requires a `tool_id` parameter (obtained from the list response) and accepts optional parameters such as `section`, `range`, or `depth` to refine the query.

The endpoint returns the concrete content in the appropriate format—Markdown for Wiki pages, raw text for code snippets, or structured data for call-graph representations. This two-step process ensures agents retrieve only the specific knowledge fragments they need rather than downloading entire knowledge bases.

## API Specifications and Source Implementation

The implementation resides in the MemoryKnowledge service component of the TencentDB-Agent-Memory repository. The following source files define the contract and behavior of these endpoints:

- **[`MemoryKnowledge/v3-api-memoryknowledge-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/v3-api-memoryknowledge-doc.md)** – Contains the formal API specification for both endpoints, including request/response schemas and parameter definitions at lines 511 and 553
- **[`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md)** – Provides high-level architectural context for the discover-then-use pattern at line 265
- **[`MemoryKnowledge/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/README.md)** – Documents environment variables controlling logging and service configuration for `/v3/tools/call` operations

Both endpoints use standard HTTP POST semantics with JSON payloads. The `/v3/tools/list` endpoint supports filtering capabilities to narrow results by tool type or metadata tags, while `/v3/tools/call` implements content negotiation based on the target tool's native format.

## Implementation Examples

The following examples demonstrate how to interact with these endpoints using Python and cURL. Adjust the `BASE_URL` and authentication headers to match your specific TencentDB Agent Memory deployment.

### Python Implementation Using Requests

```python
import requests

BASE_URL = "http://localhost:8000"  # Update to your Knowledge Service address

HEADERS = {"Content-Type": "application/json"}  # Add auth tokens if required

# Step 1: Discover available tools

list_response = requests.post(
    f"{BASE_URL}/v3/tools/list",
    headers=HEADERS,
    json={}  # Optional: add filters like {"type": "wiki"}

)
list_response.raise_for_status()
tools = list_response.json()

# Select a specific tool (example: first wiki page)

tool_id = next(t["id"] for t in tools if t["type"] == "wiki")

# Step 2: Retrieve specific content

call_payload = {
    "tool_id": tool_id,
    "params": {"section": "introduction", "depth": 2}
}
call_response = requests.post(
    f"{BASE_URL}/v3/tools/call",
    headers=HEADERS,
    json=call_payload
)
call_response.raise_for_status()
content = call_response.json()
print(content)

```

### cURL Commands for Testing

```bash
BASE_URL="http://localhost:8000"

# List all available tools

curl -s -X POST "$BASE_URL/v3/tools/list" \
     -H "Content-Type: application/json" \
     -d '{}' | jq .

# Call a specific tool (replace wiki-abc with actual tool_id)

curl -s -X POST "$BASE_URL/v3/tools/call" \
     -H "Content-Type: application/json" \
     -d '{"tool_id":"wiki-abc","params":{"section":"architecture"}}' \
     | jq .

```

## Key Source Files and Architecture

The knowledge retrieval system is organized across several key files in the TencentDB-Agent-Memory repository:

- **[`MemoryKnowledge/v3-api-memoryknowledge-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/v3-api-memoryknowledge-doc.md)** – Defines the complete API contract including request schemas, response formats, and error handling specifications for both endpoints
- **[`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md)** (root level) – Explains the architectural rationale behind the two-step discovery pattern and agent integration guidelines
- **[`MemoryKnowledge/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/README.md)** – Contains service-specific configuration options, including logging controls for `/v3/tools/call` requests and environment setup instructions

These files collectively implement the **MemoryKnowledge** service layer that powers the knowledge retrieval capabilities.

## Summary

- **`/v3/tools/list`** enables **capability discovery** by returning metadata about all registered knowledge tools, including Wiki pages, code files, and impact graphs
- **`/v3/tools/call`** performs **content retrieval** using a `tool_id` from the discovery phase, supporting optional parameters to specify sections, ranges, or depth levels
- The **two-step workflow** decouples catalog browsing from content fetching, optimizing bandwidth and allowing agents to select appropriate knowledge sources programmatically
- Implementation resides in the **MemoryKnowledge** service with formal specifications documented in [`v3-api-memoryknowledge-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v3-api-memoryknowledge-doc.md) at lines 511 and 553

## Frequently Asked Questions

### What is the difference between `/v3/tools/list` and `/v3/tools/call`?

**`/v3/tools/list`** is a discovery endpoint that returns metadata about available knowledge assets without transferring their actual content, while **`/v3/tools/call`** is an execution endpoint that retrieves the specific content of a selected tool using its unique identifier. The list endpoint answers "what can I use," and the call endpoint answers "give me the specific knowledge."

### What types of knowledge assets can be retrieved using these endpoints?

According to the source code documentation in [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md), the system supports multiple asset types including **Wiki pages** (Markdown documentation), **source-code files** (text snippets with syntax context), and **impact-path graphs** (structured dependency data). Each tool type exposes specific parameters in the `/v3/tools/call` request to navigate its content structure.

### How does the MemoryKnowledge service handle authentication for these endpoints?

The source analysis indicates that authentication headers should be added to the HTTP requests as needed by your specific deployment configuration. The [`MemoryKnowledge/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/README.md) file documents environment variables and service configuration options, though production implementations typically require API tokens or session credentials passed in the `Authorization` header alongside the `Content-Type: application/json` header.

### Can I filter the tools list to show only specific asset types?

Yes. While the endpoint accepts an empty JSON body `{}` to return all tools, the `/v3/tools/list` endpoint supports optional filter parameters in the request body. You can specify criteria such as tool type, category tags, or metadata fields to narrow the results before processing, reducing payload size and improving agent decision-making performance.