mcp-rule34

Search posts by tag

search_posts

Read-onlyIdempotent

Search rule34.xxx posts by one or more tags, then filter by media type, rating, and excluded tags to get matching post URLs, scores, and total count.

Instructions

Search rule34.xxx for posts carrying a tag, or several tags at once. Tags are written as one token, so a name said as words is joined by underscores: 'asuka langley sohryu' and 'ranma 1/2' are single tags, and this tool joins them for you. Returns each post's page, its image or video URL, dimensions, score and rating, alongside the number of posts the whole search matches. A row shows the first 12 of a post's tags and says how many it has; call get_post for the whole list with a kind for every tag. Use 'media_type' to ask for still images, animations or video; the site classifies these itself. When a search finds nothing, the answer names the tags rule34.xxx does not hold, or says how many posts the tags match once the restrictions are dropped.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`page`	No
`sort`	No	'score' is the site's own tally of votes, recomputed once a day. 'id' is newest first. 'updated' is by when a post last changed, which retagging moves. 'random' draws a different set on each call.	score
`tags`	Yes	Tags a post must all carry, such as ['asuka langley sohryu', 'black hair'].
`limit`	No
`any_of`	No	Tags a post must carry at least one of.
`rating`	No	The two ratings rule34.xxx holds. Leave unset to search both.
`exclude`	No	Tags a post must not carry, such as ['monochrome'] to leave out black and white.
`media_type`	No	'image' for stills, 'animated' for GIFs, 'video' for MP4. The site states this in its own tags, so the classification is as good as the tagging.	any

Output Schema

TableJSON Schema

Name	Required	Description
`page`	Yes
`tags`	Yes	The required tags, as rule34.xxx spells them.
`notes`	Yes
`posts`	Yes
`query`	Yes	The search as it was sent, in the site's own language.
`total`	Yes	Posts the whole search matches, as counted by the site.
`any_of`	Yes	The alternatives, as rule34.xxx spells them.
`source`	Yes
`exclude`	Yes	The excluded tags, as rule34.xxx spells them.
`has_more`	Yes
`next_page`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv2.0.1Aug 29, 2026
- removedOutput schema / properties / posts / items / properties / created_at / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / posts / items / properties / created_at / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / posts / items / properties / preview_url / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / posts / items / properties / preview_url / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / posts / items / properties / sample_url / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / posts / items / properties / sample_url / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / posts / items / properties / source / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / posts / items / properties / source / type
```
Added value: +[
+  "string",
+  "null"
+]
```
First observedv1.1.0Aug 25, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The description discloses what each result row contains, how many tags are shown, total match count, and the exact behavior when no results are found. These details meaningfully exceed the annotations, which already mark the tool as read-only and idempotent.

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?

The description is dense but every sentence earns its place: scope, tag formatting, return contents, sibling routing, media_type nuance, and empty-result behavior. It is front-loaded with the core action.

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

Completeness5/5

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

For an 8-parameter search tool, the description covers input formatting, output shape, pagination-relevant count, media filtering, and failure behavior. Since an output schema exists, nothing essential is missing for an agent to call the tool correctly.

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

Parameters4/5

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

With 75% schema coverage, the schema already documents most parameters. The description adds real value by explaining that multi-word tags are underscore-joined and that the tool performs the joining, and by clarifying that media_type relies on the site's own tagging.

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 rule34.xxx for posts carrying a tag, or several tags at once.' It also distinguishes itself from the sibling get_post by telling the agent to call get_post for a post's full tag list.

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?

It gives an explicit hand-off to get_post for the complete tag list, and explains when media_type should be used. It does not mention find_tags as an alternative, but the core search use case is unambiguous.

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

Deploy Server