genieacs-mcp

Overview Schema Source Related Servers Discussions Admin

Search devices

search_devices

Read-onlyIdempotent

Find CPE devices in GenieACS using MongoDB-style filters on tags, manufacturer, model, firmware, last inform, or TR-069 parameters; read-only queries return paginated summaries.

Instructions

Find CPE devices in GenieACS with a MongoDB-style filter: by tag, manufacturer, model, firmware version, last inform time or any TR-069 parameter. It only reads. Examples: {"_tags":"office"}; {"InternetGatewayDevice.DeviceInfo.Manufacturer":"Huawei"} (GenieACS adds ._value to parameter paths); {"_lastInform":{"$lt":"2026-01-01T00:00:00Z"}} for devices silent since that date; {"_id":{"$regex":"^202BC1-"}}. Query operators such as $eq, $ne, $gt, $lt, $in, $nin, $exists, $regex, $and and $or work; $where, $function, $accumulator and $expr are refused, and a $regex pattern may be at most 256 characters. By default each device comes back as a summary (id, last inform, tags, manufacturer, product class, serial); ask for other fields with projection. Results come in pages of limit (default 50, at most 200); page with skip.

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": "search_devices"
  }
}

Input Schema

Name	Required	Description
`skip`	No	Matching devices to skip before this page, for paging. Default 0.
`sort`	No	Sort order as a JSON object string: 1 ascending, -1 descending. Example: {"_lastInform":-1} for the most recent first.
`limit`	No	Most devices to return in this page, 1 to 200. Default 50.
`query`	Yes	The filter, as a JSON object string. Example: {"_tags":"office"} or {"_id":"202BC1-BM632w-000001"}.
`projection`	No	Comma-separated fields to return per device, e.g. "_id,InternetGatewayDevice.DeviceInfo.SoftwareVersion". Default: the summary fields. "all" returns whole device documents, which can be large (tens of KB each).

Output Schema

Name	Required	Description
`more`	Yes	true when the page is full, so more devices may match: call again with skip = skip + count.
`skip`	Yes	Devices skipped before this page.
`count`	Yes	Devices in this page.
`limit`	Yes	The page size used.
`devices`	Yes	The matching device documents, with the fields the projection asked for.

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedv0.4.1Oct 29, 2026

addedInput schema / additionalProperties
```
Added value: +false
```
addedInput schema / properties / limit / default
```
Added value: +50
```

changedInput schema / properties / limit / description

Previous value: -"Maximum number of devices to return. Defaults to 50 if not specified. Use a higher value for bulk operations, but be mindful of response size."New value: +"Most devices to return in this page, 1 to 200. Default 50."

addedInput schema / properties / limit / maximum
```
Added value: +200
```
addedInput schema / properties / limit / minimum
```
Added value: +1
```

changedInput schema / properties / limit / type

Previous value: -"string"New value: +"integer"

addedInput schema / properties / projection

Added value: +{
+  "description": "Comma-separated fields to return per device, e.g. \"_id,InternetGatewayDevice.DeviceInfo.SoftwareVersion\". Default: the summary fields. \"all\" returns whole device documents, which can be large (tens of KB each).",
+  "type": "string"
+}

changedInput schema / properties / query / description

Previous value: -"A MongoDB-style JSON query string to filter devices. Example: {\"_tags\":\"office\"} or {\"_id\":\"00236A-SmartRG585-SMRT00236a42\"}"New value: +"The filter, as a JSON object string. Example: {\"_tags\":\"office\"} or {\"_id\":\"202BC1-BM632w-000001\"}."

addedInput schema / properties / query / minLength
```
Added value: +2
```

addedInput schema / properties / skip

Added value: +{
+  "default": 0,
+  "description": "Matching devices to skip before this page, for paging. Default 0.",
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / sort

Added value: +{
+  "description": "Sort order as a JSON object string: 1 ascending, -1 descending. Example: {\"_lastInform\":-1} for the most recent first.",
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "count": {
+      "description": "Devices in this page.",
+      "type": "integer"
+    },
+    "devices": {
+      "description": "The matching device documents, with the fields the projection asked for.",
+      "items": true,
+      "type": [
+        "null",
+        "array"
+      ]
+    },
+    "limit": {
+      "description": "The page size used.",
+      "type": "integer"
+    },
+    "more": {
+      "description": "true when the page is full, so more devices may match: call again with skip = skip + count.",
+      "type": "boolean"
+    },
+    "skip": {
+      "description": "Devices skipped before this page.",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "count",
+    "limit",
+    "skip",
+    "more",
+    "devices"
+  ],
+  "type": "object"
+}

Addedv0.3.3Jun 19, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, and the description adds substantial operational context beyond that. It discloses which query operators are accepted, which are refused, the 256-character regex limit, default summary fields, projection risks when using "all", and pagination defaults and limits.

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 a single dense paragraph but is front-loaded with the purpose and then proceeds through examples, restrictions, defaults, and pagination. Every sentence provides useful query or behavior information, and there is no filler.

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 a search tool with five parameters and an output schema, the description covers purpose, query language, allowed syntax, default projections, pagination, and operator restrictions. Together with the output schema, an agent has enough information to invoke it correctly without needing to inspect sibling tools.

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

Parameters5/5

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

Schema description coverage is 100%, so the schema already documents parameters, but the description adds meaningful query semantics: MongoDB-style syntax, concrete examples, operator restrictions, projection behavior, and the size implication of requesting whole documents. This goes well beyond what the schema alone conveys.

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 states a specific verb and resource: finding CPE devices in GenieACS with a MongoDB-style filter. It scopes the searchable dimensions (tag, manufacturer, model, firmware, last inform time, TR-069 parameter) and makes clear this is a read-only search tool, which distinguishes it from sibling mutation and task-management tools.

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 gives clear usage context through concrete query examples, including common filtering patterns by tag, manufacturer, last inform time, and device ID. It does not explicitly name alternatives such as get_parameter or refresh_parameter, so it falls short of full when/when-not guidance, but the intended use case is easy to infer.

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

Deploy Server