Skip to main content
Glama
Sign In

CiteLadder

by com.citeladder
OverviewDiscussionsAdmin

Read queries by page

read_query_evidence
Read-onlyIdempotent

Read the Search Console queries that bring searchers to each site page, matched to pages CiteLadder crawled, for one saved window. Use it to see which queries a page ranks for, or which page answers a query; for totals and trends use read_performance, and for the search signals found in the same window use read_demand. The window must exactly match a saved one: read_demand returns it. Any other window returns unavailable exact_query_evidence_window_not_projected, which is not zero. Each row is one query, page and day: the query, the page Search Console reported, the crawled page it was matched to (site_url_id), how the match was made (resolution_outcome), and impressions, clicks and CTR. Rows come in pages; pass next_cursor for more. Country, device and search type are not broken out.

Input Schema

NameRequiredDescriptionDefault
limitNoHow many rows to return; omit for the default page size.
queryNoOne search query, matched exactly ignoring case and spacing, not a search.
cursorNoThe next_cursor a previous page returned.
project_idYesA project id that list_projects returned.
window_endYesLast day of the same saved window, inclusive: read_demand's window.end.
site_url_idNoA page id (site_url_id) from read_site_pages or an earlier row; keep only its queries.
window_startYesFirst day of a saved window, inclusive: read_demand's window.start.
resolution_outcomeNoKeep only queries whose page match was exact, resolved (for example through a redirect or canonical), ambiguous or unresolved. All filters combine.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changed
    • addedInput schema / properties / limit / description
      Added value: +"How many rows to return; omit for the default page size."
    • addedInput schema / properties / project_id / description
      Added value: +"A project id that list_projects returned."
    • addedInput schema / properties / query / description
      Added value: +"One search query, matched exactly ignoring case and spacing, not a search."
    • changedInput schema / properties / query / type
      Previous value: -[
-  "string",
-  "null"
-]New value: +"string"
    • addedInput schema / properties / resolution_outcome / description
      Added value: +"Keep only queries whose page match was exact, resolved (for example through a redirect or canonical), ambiguous or unresolved. All filters combine."
    • addedInput schema / properties / resolution_outcome / enum
      Added value: +[
+  "exact",
+  "resolved",
+  "ambiguous",
+  "unresolved"
+]
    • changedInput schema / properties / resolution_outcome / type
      Previous value: -[
-  "string",
-  "null"
-]New value: +"string"
    • addedInput schema / properties / site_url_id / description
      Added value: +"A page id (site_url_id) from read_site_pages or an earlier row; keep only its queries."
    • addedInput schema / properties / window_end / description
      Added value: +"Last day of the same saved window, inclusive: read_demand's window.end."
    • addedInput schema / properties / window_start / description
      Added value: +"First day of a saved window, inclusive: read_demand's window.start."
  2. 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 read-only, idempotent, non-destructive, closed-world, so the description correctly spends its words elsewhere: the strict window-match requirement, the specific unavailability error code and the warning that it is "not zero", pagination via next_cursor, and the explicit absence of country/device/search-type breakdowns. These are failure modes and data-shape constraints an agent cannot infer from the structured fields.

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?

Structure is strong: purpose first, then routing to alternatives, then the window constraint and error, then row shape and pagination. It is dense and slightly run-on in places (the error-code sentence), but essentially every sentence carries new information, 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?

There is no output schema, so the description carries the burden of describing the return shape, and it does: row granularity, the fields returned, and how to page. Combined with the window prerequisite and the disjoint-filters note ("All filters combine" in the schema), an agent has everything needed to call this correctly.

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 a baseline of 3 applies, but the description adds real meaning: it explains that rows are query/page/day and what site_url_id and resolution_outcome mean in the returned data, which illuminates the corresponding filters (site_url_id, resolution_outcome) beyond their schema text. It does not add syntax detail for query, limit or cursor beyond what the schema already says.

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 names a specific verb and resource ("Read the Search Console queries ... matched to pages CiteLadder crawled") and states the scope (one saved window, per page/day rows). It also explicitly differentiates from read_performance (totals/trends) and read_demand (search signals), so an agent can separate it from siblings without opening a 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?

It gives two concrete use cases (which queries a page ranks for; which page answers a query) and names the alternatives with the condition that selects them: read_performance for totals and trends, read_demand for signals in the same window. It also states a hard pre-condition (the window must exactly match a saved one, obtained from read_demand) and the consequence of violating it.

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