bluesky-mcp-server
Server Details
Search posts, profiles, feeds, threads, and trending topics on Bluesky.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.5/5 across 7 of 7 tools scored.
Each tool targets a distinct Bluesky resource or action - feed, follows, thread, profile, trending, actor search, post search - with no overlap in purpose. Descriptions clearly differentiate them.
All tools follow a consistent 'bsky_{verb}_{noun}' pattern in snake_case. Verbs are either 'get' for retrieval or 'search' for querying, creating a predictable and uniform naming scheme.
Seven tools is well-scoped for a read-only Bluesky client. Each tool serves a clear, necessary function without redundancy or bloat.
The tool set covers all major read operations: profiles, feeds, threads, social graph, search, and trends. Missing direct single-post retrieval and write capabilities, but these are likely out of scope.
Available Tools
7 toolsbsky_get_author_feedGet Bluesky Author FeedARead-onlyIdempotentInspect
Get a Bluesky user's recent posts ordered newest-first. Filter by post type: "posts_with_replies" (everything), "posts_no_replies" (original posts only), "posts_with_media" (posts with images or links), or "posts_and_author_threads" (posts the author started). Returns posts with full text, engagement counts, embeds, and AT-URIs for drilling into threads via bsky_get_post_thread. Supports cursor pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| actor | Yes | Handle (e.g. "alice.bsky.social") or DID of the author whose feed to fetch. | |
| limit | No | Maximum number of posts to return (1–100). Default 25. | |
| cursor | No | Opaque pagination cursor from a previous response. Omit for the first page. | |
| filter | No | Filter for post types: "posts_no_replies" for original posts only, "posts_with_replies" for everything, "posts_with_media" for posts with images/links, "posts_and_author_threads" for threads the author started. | posts_no_replies |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied to this page. |
| posts | Yes | Posts from this author, ordered newest-first. |
| shown | No | Number of posts returned on this page. |
| cursor | No | Opaque cursor for the next page. Absent on the last page. |
| notice | No | Guidance when the result set is empty or constrained. |
| truncated | No | True when more posts exist beyond this page (a cursor was returned). |
| totalReturned | Yes | Number of posts in this response page. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes behavior beyond annotations: ordering, return content (text, engagement, embeds, AT-URIs), pagination, and filter semantics. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused sentences with no redundancy. Front-loaded with purpose, then filter details, then return value and sibling link. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema and good annotations, the description covers purpose, usage, pagination, and integration with a sibling tool. No gaps for an agent to proceed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers all parameters. Description adds context like grouping filter options and explaining cursor usage, but does not add significant new meaning beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool gets a Bluesky user's recent posts newest-first, with filtering options. Distinguishes from siblings by mentioning relation to bsky_get_post_thread for thread drilling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on pagination and filter values, and hints at chaining with bsky_get_post_thread. Lacks explicit exclusions or when-not-to-use compared to other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bsky_get_followsGet Bluesky Social GraphARead-onlyIdempotentInspect
Fetch the social graph edges for a Bluesky account — who follows them, or who they follow. Returns paginated actor profiles (handle, DID, displayName, bio, follower count) plus a summary of the subject account. Accounts with large social graphs return only the first page; use cursor pagination to walk through the full list.
| Name | Required | Description | Default |
|---|---|---|---|
| actor | Yes | Handle (e.g. "alice.bsky.social") or DID of the account to query. | |
| limit | No | Maximum number of actors to return per page (1–100). Default 25. | |
| cursor | No | Opaque pagination cursor from a previous response. Omit for the first page. | |
| direction | Yes | "followers" returns accounts that follow this actor. "following" returns accounts this actor follows. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied to this page. |
| shown | No | Number of actors returned on this page. |
| actors | Yes | Actors in the requested direction of the social graph. |
| cursor | No | Opaque cursor for the next page. Absent on the last page. |
| notice | No | Guidance when the result set is empty or constrained. |
| subject | Yes | Profile summary of the queried actor. |
| truncated | No | True when more actors exist beyond this page (a cursor was returned). |
| totalReturned | Yes | Number of actors in this response page. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds essential behavioral context: pagination, that large graphs return only the first page, and the specific fields returned. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with core purpose, no fluff. Every sentence adds value: purpose, return data, pagination guidance. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description covers all necessary context: purpose, parameters (via schema), pagination, limitations, and return structure. Adequate for a tool with 4 params and a simple graph query.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are documented. The description adds meaning by explaining pagination behavior (cursor) and confirming direction parameter semantics. It contextualizes rather than just repeating schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' and clearly identifies the resource as 'social graph edges' with two directions. It distinguishes from siblings (e.g., bsky_get_author_feed, bsky_get_profile) by focusing on follower/following relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use this tool (to see who follows or is followed by an account) and provides pagination guidance for large graphs. It does not explicitly compare to siblings but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bsky_get_post_threadGet Bluesky Post ThreadARead-onlyIdempotentInspect
Fetch the full conversation for a post by AT-URI — the parent chain upward and the reply tree downward. Enter the thread at any point and traverse the full discussion. AT-URIs have the format "at:////" and are returned by bsky_search_posts and bsky_get_author_feed in the "uri" field of each post. Returns the root post, parent chain, and nested replies with per-post author and engagement data. "truncated: true" on a reply node means there are more replies below — increase depth to load them.
| Name | Required | Description | Default |
|---|---|---|---|
| uri | Yes | AT-URI of the post to fetch, e.g. "at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/abc123". Obtain from bsky_search_posts or bsky_get_author_feed. | |
| depth | No | How many levels of replies to include in the reply tree. Default 6. | |
| parent_height | No | How many parent posts to include in the parent chain above the target post. Default 80. |
Output Schema
| Name | Required | Description |
|---|---|---|
| thread | Yes | The conversation thread rooted at the requested post. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral details beyond annotations: describes return structure (root, parent chain, nested replies, author, engagement data) and truncated flag meaning. Aligns with readOnlyHint, idempotentHint, openWorldHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, front-loads purpose, uses efficient clauses. Every sentence adds value. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a thread fetch tool with output schema. Covers input parameters, return structure, truncation behavior, and how to obtain AT-URI from siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. Description adds context on AT-URI format and depth use for truncation but does not significantly expand beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Fetch', resource 'full conversation for a post', and distinguishes from sibling tools like bsky_search_posts. Specifies AT-URI format and how to obtain it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains entering at any point and traversing full discussion, and how to handle truncated replies by increasing depth. Not explicit about when not to use but context clear via sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bsky_get_profileGet Bluesky ProfileARead-onlyIdempotentInspect
Fetch a Bluesky actor's public profile by handle (e.g. "bsky.app") or DID (e.g. "did:plc:z72i7hdynmk6r22z27h6tvur"). Returns displayName, handle, DID, bio, follower/following/post counts, avatar URL, moderation labels, and pinned post AT-URI. Use this as the first step to resolve a handle to a DID before calling tools that require a DID or AT-URI. Handles and DIDs are interchangeable as input.
| Name | Required | Description | Default |
|---|---|---|---|
| actor | Yes | Handle (e.g. "bsky.app", "alice.bsky.social") or DID (e.g. "did:plc:z72i7hdynmk6r22z27h6tvur") of the actor to look up. |
Output Schema
| Name | Required | Description |
|---|---|---|
| did | Yes | Decentralized Identifier — the permanent, portable identity key for this account. |
| avatar | No | URL of the profile avatar image. |
| handle | Yes | Human-readable username, e.g. "alice.bsky.social". |
| labels | No | Moderation labels applied to this profile. |
| createdAt | No | ISO 8601 timestamp of account creation. |
| indexedAt | No | ISO 8601 timestamp when the AppView last indexed this profile. |
| postsCount | No | Total posts authored by this actor. |
| description | No | Biography / about text. |
| displayName | No | Display name set by the user. May differ from the handle. |
| followsCount | No | Number of accounts this actor follows. |
| pinnedPostUri | No | AT-URI of the pinned post, if any. Pass to bsky_get_post_thread to read it. |
| followersCount | No | Number of accounts following this actor. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only, open-world, and idempotent. The description adds value by detailing the return payload (displayName, bio, counts, etc.) and the resolution behavior, though it omits rate limits or auth context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no redundancy: action+input, return values, usage guidance. Front-loaded with the verb 'Fetch' for immediate clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a single-parameter tool with an output schema. It explains the tool's role relative to siblings and describes all key returned fields, leaving no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the parameter, but the description reinforces it with examples and clarifies that both handles and DIDs are acceptable, adding practical value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it fetches a Bluesky actor's public profile by handle or DID, listing return fields. It distinguishes itself from siblings by positioning it as a handle-to-DID resolution step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance: first step for resolving handles to DIDs before calling dependent tools. It also notes that handles and DIDs are interchangeable, giving concrete usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bsky_get_trendingGet Bluesky Trending TopicsARead-onlyInspect
Fetch the current real-time trending topics on Bluesky. Returns topics with display name, post count, category (politics, sports, pop-culture, etc.), status (hot/rising), and start time. Entry point for "what is Bluesky talking about right now". Pair with bsky_search_posts to drill into any trending topic. Note: uses the app.bsky.unspecced.getTrends endpoint, which is not part of Bluesky's stable lexicon and may change without notice.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of trending topics to return (1–25). Default 10. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied to this request. |
| shown | No | Number of trending topics returned. |
| notice | No | Guidance when the result set is empty or constrained. |
| trends | Yes | Current trending topics, ordered by prominence. |
| truncated | No | True when the topic list was capped at the requested limit; more may exist. |
| totalReturned | Yes | Number of trending topics returned. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, openWorld, not idempotent), the description warns that it uses an unspecced endpoint that may change without notice. This adds critical behavioral context not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each adding distinct value: purpose, output fields, use case, and a caution. Front-loaded with the core action and efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one simple parameter, an output schema, and clear annotations, the description covers return values, usage workflow, and endpoint instability. No gaps for an AI agent to misunderstand.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the single 'limit' parameter with description and constraints (100% coverage). The description adds no further parameter guidance, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches 'current real-time trending topics on Bluesky' with explicit output fields. This is distinct from sibling tools that focus on feeds, profiles, or search, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description identifies it as the entry point for current trending topics and suggests pairing with bsky_search_posts for deeper exploration. It provides clear context but stops short of explicitly stating when not to use it or listing alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bsky_search_actorsSearch Bluesky ActorsARead-onlyIdempotentInspect
Find Bluesky accounts by name or handle fragment. Returns ranked profiles with handle, DID, displayName, bio, and follower count. Use before bsky_get_profile or bsky_get_author_feed when you have a name but not a confirmed handle. Supports cursor-based pagination for browsing beyond the first page of results.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of actors to return (1–100). Default 25. | |
| query | Yes | Name or handle fragment to search for, e.g. "alice" or "nytimes.com". | |
| cursor | No | Opaque pagination cursor from a previous response. Note: the public Bluesky AppView restricts cursor-based search pagination for unauthenticated requests — passing a cursor may return a 403 error. Cursor pagination is reliable only for bsky_get_author_feed and bsky_get_follows. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied to this page. |
| shown | No | Number of actors returned on this page. |
| actors | Yes | Matching actor profiles, ranked by relevance. |
| cursor | No | Opaque cursor returned by the API. Unreliable for unauthenticated search requests on the public AppView — passing it on a subsequent call may return a 403 error. |
| notice | No | Guidance when the result set is empty or constrained. |
| truncated | No | True when more actors match than were returned on this page. |
| totalReturned | Yes | Number of actors in this response page. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses a critical behavioral quirk: cursor-based pagination may return a 403 error for unauthenticated requests on the public Bluesky AppView. It also clarifies the return structure (ranked profiles with specific fields). This level of detail fully informs the agent of behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, containing a clear action, result, usage guidance, and a note on pagination. It is front-loaded with the primary purpose. A slight improvement could be merging the return fields sentence for even tighter text, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (search with pagination) and the presence of an output schema, the description covers all necessary context: what it does, what it returns, when to use it, and an important pagination caveat. It is fully adequate for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has detailed descriptions for all three parameters (query, limit, cursor) with 100% coverage. The tool description adds minimal value beyond the schema: it mentions the cursor limitation but does not fundamentally change understanding of parameters. Thus, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds Bluesky accounts by name or handle fragment, specifies the returned fields (handle, DID, displayName, bio, follower count), and distinguishes itself from siblings like bsky_get_profile and bsky_get_author_feed by noting it should be used when a name is known but not a confirmed handle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent when to use this tool versus alternatives, stating 'Use before bsky_get_profile or bsky_get_author_feed when you have a name but not a confirmed handle.' Also mentions pagination and the cursor limitation (403 error), providing clear guidance on when not to rely on cursor-based pagination for search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bsky_search_postsSearch Bluesky PostsARead-onlyIdempotentInspect
Full-text search across public Bluesky posts. Filters by author (handle or DID), language (BCP-47 code, e.g. "en"), hashtag (without the # prefix), date range (ISO 8601), and sort order. Returns posts with text, author info, engagement counts (likes/reposts/replies), normalized embeds, AT-URIs for thread drilling, and hitsTotal when the API reports the total number of matching posts. This is the primary entry point for social listening — pass any AT-URI from results to bsky_get_post_thread to read the full conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Hashtag to filter by — provide without the # prefix, e.g. "ai" not "#ai". | |
| sort | No | "latest" returns posts in reverse-chronological order (default). "top" returns by engagement score. | latest |
| limit | No | Maximum posts to return (1–100). Default 25. | |
| query | Yes | Full-text search query, e.g. "climate change" or "#ai announcement". | |
| since | No | Return posts after this ISO 8601 datetime (inclusive), e.g. "2025-01-01T00:00:00Z". | |
| until | No | Return posts before this ISO 8601 datetime (inclusive), e.g. "2025-12-31T23:59:59Z". | |
| cursor | No | Opaque pagination cursor from a previous response. Note: the public Bluesky AppView restricts cursor-based search pagination for unauthenticated requests — passing a cursor may return a 403 error. Cursor pagination is reliable only for bsky_get_author_feed and bsky_get_follows. | |
| language | No | BCP-47 language code to restrict results to, e.g. "en", "ja", "es". | |
| author_handle | No | Filter to posts by this author. Accepts handle (e.g. "bsky.app") or DID. Use bsky_get_profile to resolve a name to a handle first. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied to this page. |
| posts | Yes | Posts matching the search query. |
| shown | No | Number of posts returned on this page. |
| cursor | No | Opaque cursor returned by the API. Unreliable for unauthenticated search requests on the public AppView — passing it on a subsequent call may return a 403 error. |
| notice | No | Guidance when the result set is empty or constrained. |
| hitsTotal | No | Total number of posts matching this query across all pages, when reported by the API. Use to communicate result scale without fetching every page. |
| truncated | No | True when more posts match than were returned on this page. |
| totalReturned | Yes | Number of posts in this response page. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds value by detailing what is returned (posts with text, author info, engagement counts, normalized embeds, AT-URIs, hitsTotal) and discloses a behavioral limitation: cursor pagination may return a 403 error for unauthenticated requests. This goes beyond annotations, though annotations already cover the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences. The first sentence states the purpose and filters; the second describes return values and linkage to a sibling tool. It includes a necessary caveat about cursor pagination. All information is relevant and front-loaded, with no redundant or verbose language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, 1 required, output schema exists), the description covers usage context, return values, limitations (cursor), and how to chain with other tools. The output schema is present, so return details are already structured. The description provides a complete guide for using the tool effectively in a search workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all parameters have descriptions), so baseline is 3. The description adds contextual value beyond the schema: it explains that this is the primary entry point, mentions cursor unreliability, recommends using bsky_get_profile to resolve handles, and suggests passing AT-URIs to bsky_get_post_thread. This enriches the meaning of the parameters and their usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs full-text search across public Bluesky posts, lists specific filter parameters (author, language, hashtag, date range, sort), and describes the return data (text, author info, engagement counts, etc.). It distinguishes itself from sibling tools by labeling it as the primary entry point for social listening and directing to bsky_get_post_thread for thread drilling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (primary entry point for social listening) and hints at alternatives for thread drilling via bsky_get_post_thread. It also provides a specific caveat about cursor pagination being unreliable for this tool (403 error) and that it is only reliable for bsky_get_author_feed and bsky_get_follows, guiding appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!