cyanheads-mcp-server

Search Fleet Tools and Servers

cyanheads_search_catalog

Read-only

Search fleet tools and servers by natural-language description. Returns ranked matches with brief summaries and the server each tool belongs to. Use scope "servers" to find which server handles a workflow; use the default scope "tools" to find specific tools.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of results to return (1-1000). Default 5. At most 20 per call: a larger limit returns up to 20, with a notice naming the offset to continue from when more matches follow.
`query`	Yes	Natural language search query. Describe what you want to accomplish, a workflow, or a capability area. 1-500 raw characters; surrounding whitespace is trimmed. Must contain non-whitespace text.
`scope`	No	What to search. "tools" returns individual tool matches; "servers" returns server-level matches.	tools
`offset`	No	Result offset. Use nextOffset with the same query, scope, category, and limit; pages use the current catalog.
`category`	No	Filter by catalog category. Omit to search all categories.
`serversOffset`	No	Independent server roll-up offset (10 per page). Use nextServersOffset; must be zero in servers scope.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	Per-call result cap that was applied.
`error`	No	Present when the call failed. Absent on success.
`scope`	No	Scope that was searched.
`shown`	No	Results returned on this capped page.
`notice`	No	Guidance for zero matches, an exhausted result page, or a page cut to the 20-per-call cap with more matches following (names the offset to continue from). Absent otherwise.
`offset`	No	Current ranked-result offset.
`results`	No	Ranked matches, best first.
`servers`	No	Server roll-up from the full match set, independent of result offset/limit. Tools scope only. Ordered by topScore desc (name-tiebroken); 10 per page starting at serversOffset. Use nextServersOffset to continue and serversTotal for the full distinct count.
`truncated`	No	True when limit exceeded the 20-per-call cap and more matches follow this page.
`nextOffset`	No	Next ranked-result offset, or null when exhausted.
`totalCount`	No	Total relevant matches before the limit was applied.
`serversTotal`	No	Total distinct servers in the full match set (before the cap of 10 is applied). Present only when servers is present.
`serversOffset`	No	Current server roll-up offset; tools scope only.
`effectiveQuery`	No	The query that was searched.
`nextServersOffset`	No	Next server roll-up offset, or null when exhausted; tools scope only.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedOct 19, 2026

changedInput schema / properties / limit / description

Previous value: -"Maximum number of results to return (1-20). Default 5."New value: +"Maximum number of results to return (1-1000). Default 5. At most 20 per call: a larger limit returns up to 20, with a notice naming the offset to continue from when more matches follow."

changedInput schema / properties / limit / maximum
```
Previous value: -20New value: +1000
```

addedOutput schema / properties / cap

Added value: +{
+  "description": "Per-call result cap that was applied.",
+  "type": "number"
+}

changedOutput schema / properties / notice / description

Previous value: -"Guidance for zero matches or an exhausted result page. Absent on nonempty result pages."New value: +"Guidance for zero matches, an exhausted result page, or a page cut to the 20-per-call cap with more matches following (names the offset to continue from). Absent otherwise."

changedOutput schema / properties / results / items / properties / server / description

Previous value: -"Server package name that owns this tool (e.g. \"arxiv-mcp-server\"). Same as name when scope is \"servers\"."New value: +"Server package name that owns this tool (e.g. \"arxiv-mcp-server\"). Same as name when scope is \"servers\". Pass name and server to cyanheads_describe_entry to describe exactly this row."

addedOutput schema / properties / shown

Added value: +{
+  "description": "Results returned on this capped page.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when limit exceeded the 20-per-call cap and more matches follow this page.",
+  "type": "boolean"
+}

Changed13 schema fields changedSep 30, 2026

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Result offset. Use nextOffset with the same query, scope, category, and limit; pages use the current catalog.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

changedInput schema / properties / query / description

Previous value: -"Natural language search query. Describe what you want to accomplish, a workflow, or a capability area. 1-500 characters."New value: +"Natural language search query. Describe what you want to accomplish, a workflow, or a capability area. 1-500 raw characters; surrounding whitespace is trimmed. Must contain non-whitespace text."

addedInput schema / properties / query / pattern
```
Added value: +"\\S"
```

addedInput schema / properties / serversOffset

Added value: +{
+  "default": 0,
+  "description": "Independent server roll-up offset (10 per page). Use nextServersOffset; must be zero in servers scope.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "results",
-      "scope",
-      "effectiveQuery",
-      "totalCount"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "offset",
+      "nextOffset",
+      "results",
+      "scope",
+      "effectiveQuery",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `catalog_empty`: Catalog has not finished loading. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_servers_offset`: A nonzero serversOffset is supplied in servers scope. `catalog_empty`: Catalog has not finished loading. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "catalog_empty"
-]New value: +[
+  "invalid_servers_offset",
+  "catalog_empty"
+]

addedOutput schema / properties / nextOffset

Added value: +{
+  "description": "Next ranked-result offset, or null when exhausted.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / nextServersOffset

Added value: +{
+  "description": "Next server roll-up offset, or null when exhausted; tools scope only.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

changedOutput schema / properties / notice / description

Previous value: -"Guidance when no results matched — e.g. how to broaden the query or try a different scope. Absent on successful result pages."New value: +"Guidance for zero matches or an exhausted result page. Absent on nonempty result pages."

addedOutput schema / properties / offset

Added value: +{
+  "description": "Current ranked-result offset.",
+  "type": "number"
+}

changedOutput schema / properties / servers / description

Previous value: -"Roll-up of distinct servers across the full match set, before the limit slice. Present only for scope \"tools\". Ordered by topScore desc (name-tiebroken); capped at 10. Use serversTotal to see how many distinct servers matched in total."New value: +"Server roll-up from the full match set, independent of result offset/limit. Tools scope only. Ordered by topScore desc (name-tiebroken); 10 per page starting at serversOffset. Use nextServersOffset to continue and serversTotal for the full distinct count."

addedOutput schema / properties / serversOffset

Added value: +{
+  "description": "Current server roll-up offset; tools scope only.",
+  "type": "number"
+}

Changed6 schema fields changedAug 21, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "results",
+      "scope",
+      "effectiveQuery",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `catalog_empty`: Catalog has not finished loading. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "catalog_empty"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "results",
-  "scope",
-  "effectiveQuery",
-  "totalCount"
-]

AddedJul 26, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already establish that this is a read-only, non-open-world operation, and the description adds useful substance on top: ranked results, brief summaries, and server attribution per tool. It does not discuss pagination caps or rate behavior in prose, but the schema already documents the 20-per-call limit and offset continuation.

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 tight sentences with no waste: purpose and return value first, then the scope-selection rule. Every sentence carries decision-relevant information and the most important constraint is front-loaded.

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?

With an output schema, full parameter coverage, and safety annotations, the description supplies exactly the pieces structured fields cannot: what the ranking returns and how to choose a scope. The only gap is the absence of any relationship to describe_entry, which matters for a two-tool catalog.

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 100%, so the baseline is 3, and the description earns above baseline by explaining the practical semantics of 'scope' in workflow terms rather than just restating the enum. The remaining parameters (limit, offset, category, serversOffset) are left entirely to the schema.

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

Purpose4/5

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

The description states a specific verb and resource ('Search fleet tools and servers by natural-language description') and defines the return shape ('ranked matches with brief summaries and the server each tool belongs to'). It clearly separates the two search modes internally, but never names the one sibling tool (describe_entry), so an agent gets no explicit sibling differentiation.

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 concrete routing guidance for its most consequential choice: scope 'servers' to find which server handles a workflow, default scope 'tools' to find specific tools. It stops short of saying when to prefer describe_entry over searching, so usage is clear but not exhaustive.

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

All cyanheads-mcp-server tools Inspect

Try in Browser

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.