Skip to main content
Glama

bluesky-mcp-server

Search Bluesky Feeds

bsky_search_feeds
Read-onlyIdempotent

Search metadata in the provider’s public feed catalog, without credentials. This searches feed names and descriptions, not post text, and does not enumerate every feed. Returns feeds in provider order with generator AT-URIs and creator identities; pass a feedUri to bsky_get_feed to read its posts. Uses app.bsky.unspecced.getPopularFeedGenerators, an unstable upstream API that may change or become unavailable. Continue with the returned opaque cursor and the same 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": {
      "query": "<query>"
    },
    "name": "bsky_search_feeds"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum feeds to return. Default 25; values above 100 are clamped with a notice unless read-limit clamping is disabled.
queryYesFeed catalog metadata to search, e.g. "science". Must not be blank.
cursorNoOpaque cursor from a previous response to this same query. Omit for the first page.

Output Schema

NameRequiredDescriptionDefault
capNoThe limit applied to this page.
errorNoPresent when the call failed. Absent on success.
feedsNoMatching feeds in provider order.
shownNoNumber of feeds returned on this page.
cursorNoOpaque next-page cursor. Its presence signals continuation even when feeds is empty; absent at the end.
noticeNoContinuation, empty-result, or clamping guidance.
truncatedNoTrue when a cursor is present, regardless of the number of feeds returned.
totalReturnedNoNumber of feeds on this page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `catalog_unavailable`: The unstable upstream catalog endpoint is no longer available (HTTP 404 or 410). Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_cursor`: The feed catalog returned its invalid-cursor response for a request carrying a cursor. `catalog_unavailable`: The unstable upstream catalog endpoint is no longer available (HTTP 404 or 410). Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "catalog_unavailable"
      -]New value: +[
      +  "invalid_cursor",
      +  "catalog_unavailable"
      +]
  2. Added

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the readOnly/idempotent/openWorld annotations by disclosing that results come in provider order rather than relevance order, that the catalog is not exhaustive, that the upstream app.bsky.unspecced.getPopularFeedGenerators endpoint is unstable and may vanish, and that the cursor is opaque and must be reused with the same query. These are exactly the behaviors an agent cannot infer from structured fields.

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

Conciseness4/5

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

Five dense sentences with no filler, and the scope/limitation statement is front-loaded before the pagination and instability notes. Minor deduction for reading as one unstructured block when the operational caveats (unstable API, cursor reuse) could be visually separated.

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?

An output schema exists, so return values need not be spelled out, yet the description still covers ordering, identifier shape (generator AT-URIs plus creator identities), and the pagination loop. Combined with the instability warning, an agent has everything required to call this correctly and to handle degradation.

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?

Schema coverage is already 100%, so the baseline is 3. The description nonetheless adds real semantics for cursor: it is opaque and only valid alongside the identical query, which is a coupling constraint the per-field schema text does not state. Limit clamping is left to the schema, which is fine.

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?

States a specific verb and resource ("Search metadata in the provider's public feed catalog") and immediately draws the boundary that matters: it searches feed names and descriptions, not post text. That single clause distinguishes it from bsky_search_actors and bsky_get_feed without requiring the schema to be opened.

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?

Gives clear context (no credentials needed) and an explicit next step: pass a returned feedUri to bsky_get_feed to read posts. The exclusion of post-text search implies when not to use it. It stops short of naming bsky_search_actors directly for people lookups, so routing between the two search tools is left partially to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.