> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Every tool the MCP server offers, what it costs, what it may change, and the permission it needs

The MCP server at `https://mcp.alura.io/mcp` has tools in four groups. Each tool calls the REST operations listed with it, at the same prices. You don't call tools yourself: you ask your assistant in plain words, and it picks the tool.

<Columns cols={2}>
  <Card title="Products and shops" icon="store" href="/mcp/tools/products-and-shops">
    Search and open products and shops, reviews, tags, sales history and Etsy links.
  </Card>

  <Card title="Keywords and trends" icon="magnifying-glass-chart" href="/mcp/tools/keywords">
    Search volume, competition, related keywords, top results and what's trending.
  </Card>

  <Card title="Saved research" icon="bookmark" href="/mcp/tools/saved-research">
    Read, create and change saved folders and lists.
  </Card>

  <Card title="Usage and workspaces" icon="gauge" href="/mcp/tools/account">
    API credits left, and switching between workspaces.
  </Card>
</Columns>

## Behavior hints

Every tool tells the assistant what it may change, with the standard MCP hints. Assistants use them to decide when to ask you first: ChatGPT, for example, asks before any tool that isn't read-only. Alura checks every call on its own side too, so a hint never grants access.

| Hint | What it means for Alura's tools |
| - | - |
| Read-only (`readOnlyHint`) | The tool changes nothing in Alura or on Etsy. Every research tool is read-only, and so are the tools that read saved research, usage and workspaces. |
| Destructive (`destructiveHint`) | The tool deletes or overwrites something your team relies on: `delete_saved`, `remove_from_saved_list`, `update_saved` (renames and moves) and `switch_workspace` (later calls act in another workspace). Assistants such as Claude ask before these. |
| Idempotent (`idempotentHint`) | Repeating the same call leaves things as the first call did. Every Alura tool that writes is idempotent: creating a list that already exists returns it, and adding an item twice adds it once. |

The research tools are read-only while Alura serves only items it already has. When Alura starts fetching new items from Etsy on request, the seven tools that can start a fetch will be marked as not read-only, because a call can queue work in Alura. They still change nothing on Etsy.
\| Open world (`openWorldHint`) | The tool returns public data about Etsy shops and listings, which other people wrote. Categories, saved research, usage and workspace tools work on Alura's own data only. |

No tool changes anything on Etsy. Alura's research is read-only; the only things the assistant can change are your saved folders, lists and items, and which workspace it works in.

## Permissions

Each tool needs one permission, called a scope, that you allow on the approval screen when you [connect](/connect-ai#permissions). The assistant doesn't see tools whose permission you left out.

| Scope | On the approval screen | Tools |
| - | - | - |
| `research:read` | Search and read Etsy market research | Products and shops, keywords and trends, categories |
| `saved:read` | See saved research | `list_saved`, `get_saved_list_items` |
| `saved:write` | Save research for you | Creating, changing and deleting saved folders, lists and items |
| `usage:read` | See API credit usage | `get_usage` |
| None | | `list_workspaces`, `switch_workspace`, shown only to people in more than one workspace |

## Arguments every tool takes

* **`detail`.** `detailed`, the default, returns every field the tool shows. `concise` returns the key fields, for long lists or a quick check. The price is the same.
* **`limit` and `cursor`** on list tools. Lists return 20 items by default and at most 50; reviews, shop products and related keywords at most 25. Pass a page's `next_cursor` back as `cursor` for the next page.

Results come as structured data plus a short text copy. Reviews, titles, tags and shop announcements appear only in the structured data, never in the text the assistant reads as instructions.

## Mature listings

Assistants see a little less than the REST API. Etsy's API has no flag for mature listings, so Alura counts products in Etsy's Sexual Wellness category, and every category under it, as mature. Over MCP, searches, trending, similar products, a shop's products and reviews, keyword top results and the category browser leave them out, and so do shops whose active products are all mature. Asking for one by ID or Etsy link answers `not_found`, and in a saved list it shows as `unavailable`. The REST API with an API key returns them as before.

## All tools

### [Products and shops](/mcp/tools/products-and-shops)

| Tool | What it does | Cost | Behavior | Scope |
| - | - | - | - | - |
| [`search_products`](/mcp/tools/products-and-shops#search_products) | Search Etsy products | 10 API credits per page | Read-only | `research:read` |
| [`get_products`](/mcp/tools/products-and-shops#get_products) | Get Etsy products | 1 API credit per call, or 1 API credit per item returned | Read-only | `research:read` |
| [`find_similar_products`](/mcp/tools/products-and-shops#find_similar_products) | Find similar products | 10 API credits per page | Read-only | `research:read` |
| [`get_product_tags`](/mcp/tools/products-and-shops#get_product_tags) | Get a product's tags | 1 API credit per page | Read-only | `research:read` |
| [`lookup_etsy_url`](/mcp/tools/products-and-shops#lookup_etsy_url) | Look up an Etsy URL | 1 API credit per call | Read-only | `research:read` |
| [`search_shops`](/mcp/tools/products-and-shops#search_shops) | Search Etsy shops | 10 API credits per page | Read-only | `research:read` |
| [`get_shop`](/mcp/tools/products-and-shops#get_shop) | Get an Etsy shop | 1 API credit per call | Read-only | `research:read` |
| [`list_shop_products`](/mcp/tools/products-and-shops#list_shop_products) | List a shop's products | 1 API credit per page | Read-only | `research:read` |
| [`get_reviews`](/mcp/tools/products-and-shops#get_reviews) | Get reviews | 1 API credit per page | Read-only | `research:read` |
| [`get_sales_history`](/mcp/tools/products-and-shops#get_sales_history) | Get sales history | 1 API credit per call | Read-only | `research:read` |
| [`browse_categories`](/mcp/tools/products-and-shops#browse_categories) | Browse Etsy categories | Free (0 API credits) | Read-only | `research:read` |

### [Keywords and trends](/mcp/tools/keywords)

| Tool | What it does | Cost | Behavior | Scope |
| - | - | - | - | - |
| [`get_keyword_metrics`](/mcp/tools/keywords#get_keyword_metrics) | Get keyword metrics | 1 API credit per item returned, or 1 API credit per call | Read-only | `research:read` |
| [`get_related_keywords`](/mcp/tools/keywords#get_related_keywords) | Get related keywords | 1 API credit per page, or 1 API credit per item returned | Read-only | `research:read` |
| [`get_keyword_top_results`](/mcp/tools/keywords#get_keyword_top_results) | Get a keyword's top products or shops | 10 API credits per page, or 1 API credit per item returned | Read-only | `research:read` |
| [`get_keyword_history`](/mcp/tools/keywords#get_keyword_history) | Get keyword search history | 1 API credit per call, or 1 API credit per item returned | Read-only | `research:read` |
| [`get_trending`](/mcp/tools/keywords#get_trending) | Get trending on Etsy | 10 API credits per page | Read-only | `research:read` |

### [Saved research](/mcp/tools/saved-research)

| Tool | What it does | Cost | Behavior | Scope |
| - | - | - | - | - |
| [`list_saved`](/mcp/tools/saved-research#list_saved) | List saved research | Free (0 API credits) | Read-only | `saved:read` |
| [`get_saved_list_items`](/mcp/tools/saved-research#get_saved_list_items) | Read a saved list | 1 API credit per item returned | Read-only | `saved:read` |
| [`create_saved_folder`](/mcp/tools/saved-research#create_saved_folder) | Create a saved folder | Free (0 API credits) | Writes data | `saved:write` |
| [`create_saved_list`](/mcp/tools/saved-research#create_saved_list) | Create a saved list | Free (0 API credits) | Writes data | `saved:write` |
| [`update_saved`](/mcp/tools/saved-research#update_saved) | Rename or move saved research | Free (0 API credits) | Destructive | `saved:write` |
| [`add_to_saved_list`](/mcp/tools/saved-research#add_to_saved_list) | Save to a list | Free (0 API credits) | Writes data | `saved:write` |
| [`remove_from_saved_list`](/mcp/tools/saved-research#remove_from_saved_list) | Remove from a list | Free (0 API credits) | Destructive | `saved:write` |
| [`delete_saved`](/mcp/tools/saved-research#delete_saved) | Delete a saved folder or list | Free (0 API credits) | Destructive | `saved:write` |

### [Usage and workspaces](/mcp/tools/account)

| Tool | What it does | Cost | Behavior | Scope |
| - | - | - | - | - |
| [`get_usage`](/mcp/tools/account#get_usage) | Get API usage | Free (0 API credits) | Read-only | `usage:read` |
| [`list_workspaces`](/mcp/tools/account#list_workspaces) | List workspaces | Free (0 API credits) | Read-only | None |
| [`switch_workspace`](/mcp/tools/account#switch_workspace) | Switch workspace | Free (0 API credits) | Destructive | None |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.