mastodon-mcp

Search

search

Read-onlyIdempotent

Search Mastodon for accounts, statuses, or hashtags, and fetch remote posts or profiles by pasting a URL.

Instructions

Search for accounts, statuses or hashtags. Pasting a URL here with resolve on is also how you pull in a remote post or profile your instance has never seen. Note that most instances do not full-text search public statuses: a thin result set is usually the instance's policy rather than a bad query.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "q": "<q>"
    },
    "name": "search"
  }
}

Input Schema

Name	Required	Description
`q`	Yes	Words, a hashtag, a handle, or the full URL of a post or profile.
`type`	No	Restrict the search. Omit for all three.
`limit`	No	How many of each type. Default 20.
`account`	No	Which connected account to act as. Matches a full handle (alice@example.social), a bare username (alice), or an instance (example.social). Defaults to the first connected account. Call list_accounts to see them.
`resolve`	No	Fetch a remote account or status your instance has not seen. Default true, which is what you want when passing a URL.
`account_acct`	No	Only statuses by this account.
`following_only`	No	Only accounts you already follow.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Sep 2, 2026

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations by warning that most instances do not full-text search public statuses and that a thin result set is likely instance policy, not a bad query. It also explains the remote-resolution behavior, which is non-obvious and helpful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler. The first sentence states the core purpose, the second covers the special remote-resolve use case, and the third provides a critical interpretation warning. Information is front-loaded and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only search tool with a rich input schema, the description covers the key behavioral nuance and the remote-resolution workflow. There is no output schema, and the description does not describe the result structure, but the missing return-value details are less critical for a search tool whose inputs are already fully documented. It is nearly complete for confident invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already documented in the input schema. The description reinforces the meaning of q and resolve with the URL-pasting example, but this is largely restating schema information rather than adding net-new parameter semantics. Baseline 3 is appropriate because the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Search for accounts, statuses or hashtags.' It clearly distinguishes this broad search tool from more specific sibling tools like get_account, get_hashtag_timeline, or get_status by framing it as a general query-based search. The additional mention of resolving remote URLs further clarifies a unique purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use this tool: to paste a URL and pull in a remote post or profile the instance has never seen, with resolve on. It also provides a useful normative note about interpreting thin result sets. However, it does not explicitly contrast this with sibling tools or state when not to use it, so it falls just short of full exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server