Skip to main content
Glama

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. For what answers claim about the brand, use get_reputation.

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": {
      "brand": "<brand>"
    },
    "name": "get_perception"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoEnd date, YYYY-MM-DD, inclusive; from equal to to is a single day. Defaults to today; a later date is treated as today.
fromNoStart 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.
brandYesBrand or study: its ID from list_brands, or its name (exact or a unique prefix).
max_competitorsNoCompetitors to include, best overall score first. Defaults to 8; the brand is always included.

Output Schema

NameRequiredDescriptionDefault
dataYes
generated_atYesRFC 3339 time the response was made.
schema_versionYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changed
    • 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"
      +]
  2. Changed5 schema fields changed
    • 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"
      +}
  3. Added

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already cover the read-only/idempotent safety profile, so the description wisely spends its words on non-obvious behavior: the period-scoping rule, the has_data=false empty state paired with latest_analysis_at as a recovery hint, competitor capping order, and the plan-gating note. Missing only return-shape detail, which the output schema covers.

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?

Front-loaded with the payload, then edge cases, then the sibling pointer – no filler. It is dense to the point of being a run-on in the second sentence, which costs a little readability but wastes no content.

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?

Given four parameters with full schema descriptions and an output schema, the description covers exactly the gaps structured fields cannot: empty-state semantics, how to recover from it, competitor selection order, and entitlement limits. An agent has everything needed to call this correctly and interpret a null result.

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 coverage is 100%, so the schema already documents date defaults, the 180-day cap, retention, and brand resolution. The description restates the period constraint and the competitor cap/ordering rather than adding syntax or edge cases beyond them, so baseline 3 applies.

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 concrete verb and resource – scores out of 10 on each dimension, by model, with evidence quotes and trend – and explicitly contrasts scope with get_reputation ('what answers claim about the brand'). An agent can distinguish it from the large sibling set without opening the schema.

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?

Names the alternative tool and the condition that selects it ('For what answers claim about the brand, use get_reputation'), plus a plan-availability caveat. It lacks an explicit negative case for the sibling in the other direction (e.g. when not to use perception), but routing is clear.

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.

Resources