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

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 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 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 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 – Contains the formal API specification for both endpoints, including request/response schemas and parameter definitions at lines 511 and 553
• README.md – Provides high-level architectural context for the discover-then-use pattern at line 265
• 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

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

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 – Defines the complete API contract including request schemas, response formats, and error handling specifications for both endpoints
• README.md (root level) – Explains the architectural rationale behind the two-step discovery pattern and agent integration guidelines
• 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 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}