Skip to content

Commit 5d8462d

Browse files
kostasuser01grkostasuser01gr
committed
docs(tools): add missing READMEs for Exa and Mattermost tools
1 parent 76a7dd4 commit 5d8462d

2 files changed

Lines changed: 177 additions & 79 deletions

File tree

‎tools/src/aden_tools/tools/exa_search_tool/README.md‎

Lines changed: 73 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,92 @@
11
# Exa Search Tool
22

3-
AI-powered web search, content extraction, and research using the Exa API.
3+
AI-powered web search and content extraction using the Exa (formerly Metaphor) API.
44

55
## Description
66

7-
Provides four tools for interacting with web content:
8-
9-
- **`exa_search`** — Neural/keyword web search with domain and date filters
10-
- **`exa_find_similar`** — Find pages similar to a given URL
11-
- **`exa_get_contents`** — Extract full text from URLs
12-
- **`exa_answer`** — Get citation-backed answers to questions
13-
14-
## Arguments
15-
16-
### `exa_search`
17-
18-
| Argument | Type | Required | Default | Description |
19-
| ---------------------- | --------- | -------- | ------- | ----------------------------------------------- |
20-
| `query` | str | Yes | - | The search query (1-500 chars) |
21-
| `num_results` | int | No | `10` | Number of results (1-20) |
22-
| `search_type` | str | No | `auto` | Search mode: "auto", "neural", or "keyword" |
23-
| `include_domains` | list[str] | No | `None` | Only include results from these domains |
24-
| `exclude_domains` | list[str] | No | `None` | Exclude results from these domains |
25-
| `start_published_date` | str | No | `None` | Filter by publish date (ISO 8601) |
26-
| `end_published_date` | str | No | `None` | Filter by publish date (ISO 8601) |
27-
| `include_text` | bool | No | `True` | Include full page text |
28-
| `include_highlights` | bool | No | `False` | Include relevant text highlights |
29-
| `category` | str | No | `None` | Category filter (e.g. "research paper", "news") |
30-
31-
### `exa_find_similar`
32-
33-
| Argument | Type | Required | Default | Description |
34-
| ----------------- | --------- | -------- | ------- | --------------------------------------- |
35-
| `url` | str | Yes | - | Source URL to find similar pages for |
36-
| `num_results` | int | No | `10` | Number of results (1-20) |
37-
| `include_domains` | list[str] | No | `None` | Only include results from these domains |
38-
| `exclude_domains` | list[str] | No | `None` | Exclude results from these domains |
39-
| `include_text` | bool | No | `True` | Include full page text |
40-
41-
### `exa_get_contents`
42-
43-
| Argument | Type | Required | Default | Description |
44-
| -------------------- | --------- | -------- | ------- | ----------------------------------- |
45-
| `urls` | list[str] | Yes | - | URLs to extract content from (1-10) |
46-
| `include_text` | bool | No | `True` | Include full page text |
47-
| `include_highlights` | bool | No | `False` | Include relevant highlights |
48-
49-
### `exa_answer`
50-
51-
| Argument | Type | Required | Default | Description |
52-
| ------------------- | ---- | -------- | ------- | ------------------------------------ |
53-
| `query` | str | Yes | - | The question to answer (1-500 chars) |
54-
| `include_citations` | bool | No | `True` | Include source citations |
7+
Exa is a neural search engine that understands semantic meaning rather than just keywords. Use this tool for high-quality research, finding similar pages, extracting clean page content, and getting citation-backed answers.
8+
9+
## Tools
10+
11+
### exa_search
12+
Search the web using Exa's AI-powered neural or keyword search.
13+
14+
| Argument | Type | Required | Default | Description |
15+
|----------|------|----------|---------|-------------|
16+
| `query` | str | Yes | - | The search query (1-500 chars) |
17+
| `num_results` | int | No | `10` | Number of results (1-20) |
18+
| `search_type` | str | No | `"auto"` | Mode: "auto", "neural" (semantic), or "keyword" |
19+
| `include_domains` | list | No | `None` | Only include results from these domains |
20+
| `exclude_domains` | list | No | `None` | Exclude results from these domains |
21+
| `start_published_date`| str | No | `None` | Filter by publish date start (ISO 8601, e.g. "2024-01-01") |
22+
| `end_published_date` | str | No | `None` | Filter results published before this date (ISO 8601) |
23+
| `include_text` | bool | No | `True` | Include full page text in results |
24+
| `include_highlights` | bool | No | `False` | Include relevant text highlights |
25+
| `category` | str | No | `None` | Category filter (e.g. "research paper", "news", "company") |
26+
27+
### exa_find_similar
28+
Find web pages semantically similar to a given URL.
29+
30+
| Argument | Type | Required | Default | Description |
31+
|----------|------|----------|---------|-------------|
32+
| `url` | str | Yes | - | The source URL to find similar pages for |
33+
| `num_results` | int | No | `10` | Number of similar results (1-20) |
34+
| `include_domains` | list | No | `None` | Only include results from these domains |
35+
| `exclude_domains` | list | No | `None` | Exclude results from these domains |
36+
| `include_text` | bool | No | `True` | Include full page text in results |
37+
38+
### exa_get_contents
39+
Extract clean content (text and highlights) from one or more URLs.
40+
41+
| Argument | Type | Required | Default | Description |
42+
|----------|------|----------|---------|-------------|
43+
| `urls` | list | Yes | - | List of URLs to extract content from (1-10 URLs) |
44+
| `include_text` | bool | No | `True` | Include full page text |
45+
| `include_highlights` | bool | No | `False` | Include relevant text highlights |
46+
47+
### exa_answer
48+
Get a direct answer to a question with citations from web sources.
49+
50+
| Argument | Type | Required | Default | Description |
51+
|----------|------|----------|---------|-------------|
52+
| `query` | str | Yes | - | The question to answer (1-500 chars) |
53+
| `include_citations` | bool | No | `True` | Include source citations in the response |
54+
55+
### Specialized Search Wrappers
56+
57+
The toolkit also includes convenience wrappers for specific content types:
58+
- **exa_search_news**: Pre-configured for recent news with `days_back` filter.
59+
- **exa_search_papers**: Pre-configured for research papers with `year_start` filter.
60+
- **exa_search_companies**: Pre-configured for company and startup discovery.
5561

5662
## Environment Variables
5763

58-
| Variable | Required | Description |
59-
| ------------- | -------- | --------------------------------------------------------------- |
60-
| `EXA_API_KEY` | Yes | API key from [Exa Dashboard](https://dashboard.exa.ai/api-keys) |
64+
| Variable | Required | Description |
65+
|----------|----------|-------------|
66+
| `EXA_API_KEY` | Yes | API key from [Exa Dashboard](https://dashboard.exa.ai/) |
6167

6268
## Example Usage
6369

6470
```python
65-
# Neural web search
66-
result = exa_search(query="latest advances in quantum computing")
67-
68-
# Search with filters
69-
result = exa_search(
70-
query="AI safety research",
71-
search_type="neural",
72-
include_domains=["arxiv.org", "openai.com"],
73-
start_published_date="2024-01-01",
74-
num_results=5,
75-
)
76-
77-
# Find pages similar to a URL
78-
result = exa_find_similar(url="https://example.com/article")
79-
80-
# Extract content from URLs
81-
result = exa_get_contents(urls=["https://example.com/page1", "https://example.com/page2"])
82-
83-
# Get a citation-backed answer
84-
result = exa_answer(query="What are the main causes of climate change?")
71+
# Semantic search for specific topics
72+
result = exa_search(query="latest breakthroughs in battery technology", category="research paper")
73+
74+
# Find similar content
75+
result = exa_find_similar(url="https://example.com/blog-post")
76+
77+
# Get an answer with citations
78+
result = exa_answer(query="What are the current top 3 AI companies in Japan?")
79+
80+
# Search recent news
81+
result = exa_search_news(query="Nvidia stock", days_back=2)
8582
```
8683

8784
## Error Handling
8885

8986
Returns error dicts for common issues:
90-
91-
- `Exa credentials not configured` - EXA_API_KEY not set
92-
- `Query must be 1-500 characters` - Empty or too long query
93-
- `URL is required` - Missing URL for find_similar
94-
- `At least one URL is required` - Empty URL list for get_contents
95-
- `Maximum 10 URLs per request` - Too many URLs for get_contents
87+
- `Exa credentials not configured` - Missing `EXA_API_KEY`
9688
- `Invalid Exa API key` - API key rejected (401)
9789
- `Exa rate limit exceeded` - Too many requests (429)
98-
- `Exa search request timed out` - Request exceeded 30s timeout
90+
- `Query must be 1-500 characters` - Invalid query length
91+
- `Maximum 10 URLs per request` - URL list too long for `exa_get_contents`
92+
- `Exa search request timed out` - Request timed out (30s)

‎tools/src/aden_tools/tools/mattermost_tool/README.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Mattermost Tool
2+
3+
Interact with Mattermost servers for team collaboration and messaging.
4+
5+
## Description
6+
7+
The Mattermost tool allows agents to list teams and channels, send messages, retrieve posts, and manage reactions on a Mattermost server. It supports both cloud and self-hosted instances.
8+
9+
## Tools
10+
11+
### mattermost_list_teams
12+
List all teams the authenticated user belongs to.
13+
14+
| Argument | Type | Required | Default | Description |
15+
|----------|------|----------|---------|-------------|
16+
| `account` | str | No | `""` | Optional account alias for multi-account setups |
17+
18+
### mattermost_list_channels
19+
List public channels for a specific team.
20+
21+
| Argument | Type | Required | Default | Description |
22+
|----------|------|----------|---------|-------------|
23+
| `team_id` | str | Yes | - | ID of the team |
24+
| `per_page`| int | No | `100` | Max channels to return (1-200) |
25+
| `account` | str | No | `""` | Optional account alias |
26+
27+
### mattermost_get_channel
28+
Get detailed information about a channel.
29+
30+
| Argument | Type | Required | Default | Description |
31+
|----------|------|----------|---------|-------------|
32+
| `channel_id` | str | Yes | - | ID of the channel |
33+
| `account` | str | No | `""` | Optional account alias |
34+
35+
### mattermost_send_message
36+
Send a message (post) to a channel. Supports Markdown.
37+
38+
| Argument | Type | Required | Default | Description |
39+
|----------|------|----------|---------|-------------|
40+
| `channel_id` | str | Yes | - | ID of the channel to post in |
41+
| `message` | str | Yes | - | Message text (max 16383 chars) |
42+
| `root_id` | str | No | `""` | ID of the parent post for threading |
43+
| `account` | str | No | `""` | Optional account alias |
44+
45+
### mattermost_get_posts
46+
Retrieve posts from a channel with pagination support.
47+
48+
| Argument | Type | Required | Default | Description |
49+
|----------|------|----------|---------|-------------|
50+
| `channel_id` | str | Yes | - | ID of the channel |
51+
| `per_page` | int | No | `60` | Max posts to return (1-200) |
52+
| `page` | int | No | `0` | Page number for pagination |
53+
| `before` | str | No | `""` | Post ID to get posts before |
54+
| `after` | str | No | `""` | Post ID to get posts after |
55+
| `account` | str | No | `""` | Optional account alias |
56+
57+
### mattermost_create_reaction
58+
Add an emoji reaction to a specific post.
59+
60+
| Argument | Type | Required | Default | Description |
61+
|----------|------|----------|---------|-------------|
62+
| `post_id` | str | Yes | - | ID of the post to react to |
63+
| `emoji_name` | str | Yes | - | Emoji name (e.g., "thumbsup", "heart") |
64+
| `account` | str | No | `""` | Optional account alias |
65+
66+
### mattermost_delete_post
67+
Delete an existing post.
68+
69+
| Argument | Type | Required | Default | Description |
70+
|----------|------|----------|---------|-------------|
71+
| `post_id` | str | Yes | - | ID of the post to delete |
72+
| `account` | str | No | `""` | Optional account alias |
73+
74+
## Environment Variables
75+
76+
| Variable | Required | Description |
77+
|----------|----------|-------------|
78+
| `MATTERMOST_URL` | Yes | Base URL of your Mattermost server (e.g. `https://mattermost.example.com`) |
79+
| `MATTERMOST_ACCESS_TOKEN` | Yes | Personal access token from your Mattermost profile |
80+
81+
## Example Usage
82+
83+
```python
84+
# List teams to get team_id
85+
teams = mattermost_list_teams()
86+
87+
# List channels for a team
88+
channels = mattermost_list_channels(team_id="your-team-id")
89+
90+
# Send a message to a channel
91+
mattermost_send_message(channel_id="your-channel-id", message="Hello from Aden Hive! 🚀")
92+
93+
# Reply to a thread
94+
mattermost_send_message(channel_id="your-channel-id", message="Replying to this thread.", root_id="parent-post-id")
95+
```
96+
97+
## Error Handling
98+
99+
Returns error dicts for common issues:
100+
- `Mattermost credentials not configured` - Missing access token or URL
101+
- `HTTP 401: Unauthorized` - Invalid access token
102+
- `HTTP 404: Not Found` - Invalid team or channel ID
103+
- `Message exceeds 16383 character limit` - Provided message is too long
104+
- `Mattermost rate limit exceeded` - Too many requests (429)

0 commit comments

Comments
 (0)