Toolsets and tools

The AmICited MCP server registers over 300 tools, one for everything the dashboard can do. Handing all of those definitions to a model on every request would use a large share of its context before it did any work, and models pick tools worse from a very long list. So the server discloses them progressively: your client sees a short list, and the agent looks up the rest when it needs them.

You do not have to manage any of this. Agents follow the pattern on their own, guided by the server’s instructions and the using-amicited skill. This page explains what they are doing so you can read a transcript, or narrow the surface on purpose.

What your client sees#

tools/list advertises a small, fixed set:

Because this list never changes during a conversation, the client’s prompt cache stays valid, which keeps long sessions fast and cheap.

Find, inspect, run#

Every other tool is reached in three steps:

search_tools  {"query": "which prompts cite competitors but not us"}
describe_tool {"name": "seo_get_citation_gap_invisible_winners"}
read_tool     {"name": "seo_get_citation_gap_invisible_winners", "arguments": {...}}

• search_tools ranks tools by name, description and toolset. It works best with the question in plain words (“is the site down”, “customer lifetime value”) rather than a half-remembered name. Pass toolset with an empty query to browse one area, and raise offset to page through a large one.
• describe_tool returns the real argument schema and the tool’s kind. Agents should always call it before running a tool, because some tools take flat arguments and others a nested query object.
• read_tool runs tools whose kind is read: free, repeatable reads of your own data. It refuses anything else, which is why it is marked read-only and why cautious clients (for example Codex with approvals turned off) can use it without stopping to ask.
• run_tool runs everything, including the other three kinds:

A tool that is not advertised is not less protected. Every tool checks permissions, plan limits and credits itself, and run_tool applies the target tool’s own write check, so a read-only token cannot reach a write through it.

The twelve toolsets#

Every tool belongs to exactly one toolset. Agents use them to decide where to search, and you can use them to pin an area (see below).

Tool names are prefixed by area (gsc_, bing_wmt_, google_ppc_, meta_, eshop_, uptime_, ads_), which makes transcripts easy to scan.

Pinning toolsets with ?toolsets=#

Some clients handle a nested run_tool call poorly, and sometimes you want a narrow agent that only sees one area. Add a query parameter to the connection URL:

https://api.flowhunt.io/mcp/amicited?toolsets=eshop,uptime
https://api.flowhunt.io/mcp/amicited?toolsets=all

The named toolsets are then advertised natively in tools/list, next to the core set. all advertises everything, which gives up the context savings, so use it only with clients that do their own tool search. Unknown names are ignored rather than rejected, so check the spelling if an area does not appear. The selection is fixed for the life of the connection; no tool can widen it mid-conversation.

Pages, fields and limits#

• Pages of 25 rows. Every tool that returns a list of rows returns 25 by default, up to a maximum of 500 per call. When more rows exist, the response includes a paging block with has_more and the value to pass on the next call (a native offset or page, or a next_cursor).
• fields. Tools that return one list of rows accept a fields array to return only the columns you need. A column the rows do not have is refused, not ignored.
• No workspace argument. The workspace is fixed by your credential, so no tool accepts a workspace id. Almost every tool does need a domain_id from list_domains.
• Hourly cap. Tool calls are counted per workspace per hour (see connect). Listing tools and reading skills are free; a hidden tool reached through read_tool or run_tool counts once.

Related#