Cleotic

Get perception

get_perception

Read-onlyIdempotent

How AI answers describe the brand and its competitors: scores out of 10 on each dimension, by model, with the brand's evidence quotes and trend. Only analysis inside the period is used; has_data is false when there is none, and latest_analysis_at then says which period to ask for. Competitors are capped, best score first. Not included on every plan.

Input Schema

TableJSON Schema

Name	Required	Description
`to`	No	End date, YYYY-MM-DD, inclusive; from equal to to is a single day. Defaults to today; a later date is treated as today.
`from`	No	Start date, YYYY-MM-DD. Defaults to 30 days before to. Windows are at most 180 days and a from after today is refused; a plan with limited history serves only the days it keeps and says so in retention.
`brand`	Yes	Brand or study: its ID from list_brands, or its name (exact or a unique prefix).
`max_competitors`	No	Competitors to include, best overall score first. Defaults to 8; the brand is always included.

Output Schema

TableJSON Schema

Name	Required	Description
`data`	Yes
`generated_at`	Yes	RFC 3339 time the response was made.
`schema_version`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedOct 1, 2026

changedInput schema / properties / from / description

Previous value: -"Start date, YYYY-MM-DD. Defaults to 30 days before to; plan retention may shorten it."New value: +"Start date, YYYY-MM-DD. Defaults to 30 days before to. Windows are at most 180 days and a from after today is refused; a plan with limited history serves only the days it keeps and says so in retention."

addedInput schema / properties / max_competitors

Added value: +{
+  "description": "Competitors to include, best overall score first. Defaults to 8; the brand is always included.",
+  "maximum": 20,
+  "minimum": 0,
+  "type": "integer"
+}

changedInput schema / properties / to / description

Previous value: -"End date, YYYY-MM-DD. Defaults to today."New value: +"End date, YYYY-MM-DD, inclusive; from equal to to is a single day. Defaults to today; a later date is treated as today."

addedOutput schema / properties / data / properties / analysed_at

Added value: +{
+  "description": "When the newest analysis in the period ran; empty without data.",
+  "type": "string"
+}

changedOutput schema / properties / data / properties / brands / description

Previous value: -"The brand first, then competitors by overall score."New value: +"The brand first, then up to max_competitors competitors by overall score. Brands without scores are left out."

changedOutput schema / properties / data / properties / brands / items / properties / evidence / description

Previous value: -"Why each dimension scored as it did, with quotes; the brand only."New value: +"Why each dimension scored as it did, with quotes; the brand only. Dimensions with no real evidence are left out."

addedOutput schema / properties / data / properties / competitors_omitted

Added value: +{
+  "description": "Scored competitors left out by max_competitors.",
+  "type": "integer"
+}

addedOutput schema / properties / data / properties / competitors_total

Added value: +{
+  "description": "Competitors with scores in the period.",
+  "type": "integer"
+}

addedOutput schema / properties / data / properties / evidence_available

Added value: +{
+  "description": "False when the analysis has scores but no evidence quotes for the brand.",
+  "type": "boolean"
+}

changedOutput schema / properties / data / properties / has_data / description

Previous value: -"False when no perception analysis falls in the period; scores are then empty."New value: +"False when no perception analysis falls in the period; brands is then empty."

addedOutput schema / properties / data / properties / latest_analysis_at

Added value: +{
+  "description": "Set when the period has no analysis: the newest analysis there is. Ask for a period that includes it.",
+  "type": "string"
+}

addedOutput schema / properties / data / properties / models_covered

Added value: +{
+  "description": "Model families the brand's scores come from.",
+  "type": "integer"
+}

addedOutput schema / properties / data / properties / models_expected

Added value: +{
+  "description": "Model families the plan collects from.",
+  "type": "integer"
+}

changedOutput schema / properties / data / required

Previous value: -[
-  "brand",
-  "period",
-  "has_data",
-  "notice",
-  "brands",
-  "trend"
-]New value: +[
+  "brand",
+  "period",
+  "has_data",
+  "notice",
+  "analysed_at",
+  "latest_analysis_at",
+  "models_covered",
+  "models_expected",
+  "evidence_available",
+  "brands",
+  "competitors_total",
+  "competitors_omitted",
+  "trend"
+]

Changed5 schema fields changedOct 1, 2026

addedInput schema / additionalProperties
```
Added value: +false
```
addedInput schema / properties / brand / minLength
```
Added value: +1
```
addedInput schema / properties / from / format
```
Added value: +"date"
```
addedInput schema / properties / to / format
```
Added value: +"date"
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "data": {
+      "additionalProperties": false,
+      "properties": {
+        "brand": {
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "url": {
+              "description": "The brand's website, or empty when none is set.",
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "name",
+            "url"
+          ],
+          "type": "object"
+        },
+        "brands": {
+          "description": "The brand first, then competitors by overall score.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "brand": {
+                "additionalProperties": false,
+                "properties": {
+                  "id": {
+                    "type": "string"
+                  },
+                  "name": {
+                    "type": "string"
+                  },
+                  "url": {
+                    "description": "The brand's website, or empty when none is set.",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "id",
+                  "name",
+                  "url"
+                ],
+                "type": "object"
+              },
+              "by_model": {
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "model": {
+                      "type": "string"
+                    },
+                    "model_name": {
+                      "type": "string"
+                    },
+                    "overall": {
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "model",
+                    "model_name",
+                    "overall"
+                  ],
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "dimensions": {
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "dimension": {
+                      "type": "string"
+                    },
+                    "score": {
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "dimension",
+                    "score"
+                  ],
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "evidence": {
+                "description": "Why each dimension scored as it did, with quotes; the brand only.",
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "captured_at": {
+                      "type": "string"
+                    },
+                    "dimension": {
+                      "type": "string"
+                    },
+                    "narrative": {
+                      "type": "string"
+                    },
+                    "negative_quotes": {
+                      "items": {
+                        "additionalProperties": false,
+                        "properties": {
+                          "answer_id": {
+                            "type": "string"
+                          },
+                          "model": {
+                            "type": "string"
+                          },
+                          "quote": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "quote",
+                          "answer_id",
+                          "model"
+                        ],
+                        "type": "object"
+                      },
+                      "type": "array"
+                    },
+                    "positive_quotes": {
+                      "items": {
+                        "additionalProperties": false,
+                        "properties": {
+                          "answer_id": {
+                            "type": "string"
+                          },
+                          "model": {
+                            "type": "string"
+                          },
+                          "quote": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "quote",
+                          "answer_id",
+                          "model"
+                        ],
+                        "type": "object"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": [
+                    "dimension",
+                    "narrative",
+                    "positive_quotes",
+                    "negative_quotes",
+                    "captured_at"
+                  ],
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "is_you": {
+                "type": "boolean"
+              },
+              "overall": {
+                "description": "Average of the dimension scores, 0-10; null without data.",
+                "type": [
+                  "null",
+                  "number"
+                ]
+              },
+              "summary": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "brand",
+              "is_you",
+              "overall",
+              "dimensions",
+              "by_model",
+              "summary",
+              "evidence"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "has_data": {
+          "description": "False when no perception analysis falls in the period; scores are then empty.",
+          "type": "boolean"
+        },
+        "notice": {
+          "type": "string"
+        },
+        "period": {
+          "additionalProperties": false,
+          "properties": {
+            "from": {
+              "description": "First day, YYYY-MM-DD.",
+              "type": "string"
+            },
+            "to": {
+              "description": "Last day, YYYY-MM-DD.",
+              "type": "string"
+            }
+          },
+          "required": [
+            "from",
+            "to"
+          ],
+          "type": "object"
+        },
+        "trend": {
+          "description": "The brand's overall score by day.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "date": {
+                "type": "string"
+              },
+              "score": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "date",
+              "score"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "brand",
+        "period",
+        "has_data",
+        "notice",
+        "brands",
+        "trend"
+      ],
+      "type": "object"
+    },
+    "generated_at": {
+      "description": "RFC 3339 time the response was made.",
+      "type": "string"
+    },
+    "schema_version": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "schema_version",
+    "generated_at",
+    "data"
+  ],
+  "type": "object"
+}

AddedSep 30, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so this is judged on added context. The description adds real behavioral detail: empty-period handling with has_data/latest_analysis_at, a cap on competitors ordered best-first, period-scoped analysis, and a plan-availability caveat — none of which the annotations express.

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?

A single front-loaded paragraph that leads with what is returned, then layers in the empty-data contract and plan caveat. Dense but every sentence carries distinct information; no filler sentences.

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 present, the description need not explain return values, and it correctly focuses on gating (plan availability), empty-result behavior, and period scoping. An agent has almost everything needed; the only gap is explicit sibling routing.

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

Parameters3/5

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

Schema description coverage is 100%, so period bounds, retention limits, brand resolution, and the max_competitors cap/ordering are already fully documented in the schema. The description restates competitor capping and period scoping without adding syntax beyond the schema, so baseline 3 applies.

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?

States a specific verb+resource (perception of the brand and its competitors) and defines the return shape precisely: scores out of 10 per dimension, by model, with evidence quotes and trend. It does not, however, distinguish itself from nearby siblings such as get_brand_overview, so the agent must infer which tool to reach for.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives useful operational context (analysis is scoped to the period, has_data is false when empty, latest_analysis_at points to a valid period) and warns it is not on every plan. But it never states when to choose this over alternatives like get_brand_overview — usage is implied rather than routed.

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

All Cleotic tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?