Skip to main content
Glama
Sign In

CiteLadder

by com.citeladder
OverviewDiscussionsAdmin

Read visibility trends

read_visibility_trends
Read-onlyIdempotent

Read how visibility changed over an explicit window of at most 366 days, as points per run or per day, week or month. Each point has the visibility score, brand mention and citation rates, share of voice, competitor rankings, the model and whether web search was on, and a comparison_key. Points with different comparison keys were measured differently and are not comparable; gaps are missing runs, not zero. At most the newest 100 points are returned. unavailable no_measured_runs means no run fell in the window. Use read_visibility_overview for one run in depth, or with baseline_id to compare exactly two runs.

Input Schema

NameRequiredDescriptionDefault
to_atYesEnd of the window, after from_at and at most 366 days later.
cohortNocore is the scored prompts (the default); comparison is the prompts that also name a competitor, reported separately; all is both.core
engineNoRead one engine only; omit for every engine.
from_atYesStart of the window, with a UTC offset, such as 2026-09-01T00:00:00Z.
market_idNoA market id from get_project_business_context; omit for the default market. Markets are never pooled.
project_idYesA project id that list_projects returned.
granularityNoOne point per run (the default), or per day, week or month.run
transport_modelNoKeep only runs answered by this model, as a previous point named it.
retrieval_enabledNotrue keeps only runs with web search on; false only runs without it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changed
    • addedInput schema / properties / cohort / description
      Added value: +"core is the scored prompts (the default); comparison is the prompts that also name a competitor, reported separately; all is both."
    • addedInput schema / properties / engine / description
      Added value: +"Read one engine only; omit for every engine."
    • addedInput schema / properties / from_at / description
      Added value: +"Start of the window, with a UTC offset, such as 2026-09-01T00:00:00Z."
    • addedInput schema / properties / granularity / description
      Added value: +"One point per run (the default), or per day, week or month."
    • addedInput schema / properties / market_id / description
      Added value: +"A market id from get_project_business_context; omit for the default market. Markets are never pooled."
    • addedInput schema / properties / project_id / description
      Added value: +"A project id that list_projects returned."
    • addedInput schema / properties / retrieval_enabled / description
      Added value: +"true keeps only runs with web search on; false only runs without it."
    • changedInput schema / properties / retrieval_enabled / type
      Previous value: -[
-  "boolean",
-  "null"
-]New value: +"boolean"
    • addedInput schema / properties / to_at / description
      Added value: +"End of the window, after from_at and at most 366 days later."
    • addedInput schema / properties / transport_model / description
      Added value: +"Keep only runs answered by this model, as a previous point named it."
  2. Changed1 schema field changed
    • changedInput schema / properties / cohort / enum
      Previous value: -[
-  "core",
-  "comparison"
-]New value: +[
+  "core",
+  "comparison",
+  "all"
+]
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real behavioral context on top: the 100-point truncation cap, the semantics of comparison_key (points with different keys are not comparable), that gaps mean missing runs rather than zero, and the unavailable/no_measured_runs error meaning. These are the operational details an agent needs to interpret results correctly.

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?

Dense but front-loaded: the core action and window constraint lead, followed by point contents, caveats, and the sibling routing. The enumeration of point fields is slightly list-heavy, but every sentence carries information an agent needs, with 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?

With no output schema, the description carries the burden of describing returns, and it does: point fields, the 100-point cap, comparison_key incomparability, gap semantics, and the no_measured_runs error. Nothing material for correct invocation or interpretation appears to be missing.

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 description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it frames granularity as the shape of a point (per run vs per day/week/month), ties the 366-day cap to the from_at/to_at pair, and explains that comparison_key distinctions make points non-comparable, which is not evident from the field name alone.

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 specific verb+resource ('Read how visibility changed over an explicit window') with the scope constraint (at most 366 days) baked in. It explicitly differentiates itself from read_visibility_overview and read_visibility_results, so an agent can route without opening either schema.

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

Usage Guidelines5/5

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

Names the alternative tool and the conditions that select it: read_visibility_overview for one run in depth, or with baseline_id to compare exactly two runs. The window and granularity constraints further scope when this tool applies, leaving little to inference.

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

All CiteLadder toolsInspect
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