Skip to main content
Glama
applyra-io

@applyra/mcp-server

by applyra-io
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Get keyword rank history

get_keyword_rank_history
Read-only

Retrieve daily rank history for a tracked keyword across apps, including events like notes and updates that may explain rank changes.

Instructions

Get the daily rank history of one tracked keyword, with one series per app that tracks it. Returns keyword, store, country, lang, the resolved from/to dates, and apps[] entries holding app_id, app_title and history[] of { date (YYYY-MM-DD), rank }, one entry per day a ranking run measured: rank is null on days the app did not rank, and a day not measured yet (today before the daily update) is omitted. Each app entry also has events { notes[], app_updates[], store_updates[] } over the range: the user's notes on the app, its updates detected, and the store algorithm updates of the keyword's market, what may explain a move. Defaults to the last 30 days. The window is capped at 400 days and at the plan history depth: a start date beyond it returns a PLAN_LIMIT error. Reversed dates are swapped and future dates are clamped to today. Pass keyword_id from list_keywords, and app_id to narrow the output to one app. For the visibility of a whole app rather than one keyword, use get_app_score_history.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
toNoEnd date in YYYY-MM-DD format. Defaults to today.
fromNoStart date in YYYY-MM-DD format. Defaults to 30 days ago.
app_idNoFilter by specific app ID
keyword_idYesThe keyword internal ID (numeric, from list_keywords results)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.6.1
    • removedInput schema / additionalProperties
      Removed value: -false
  2. First observedv1.4.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description goes well beyond them: it discloses the 400-day window cap, the plan-based history depth with a PLAN_LIMIT error, date coercion rules (reversed dates swapped, future dates clamped), the 30-day default, and rank-null vs. omitted-day semantics.

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 what is returned before the constraint rules, and nearly every sentence carries distinct information (return shape, defaults, caps, error, coercion, routing). It is dense and slightly long, but the structure is logical and there is little redundancy.

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 fully compensates by enumerating the returned fields (keyword, store, country, lang, resolved from/to, apps[] with history[] and events) and edge-case semantics. An agent has everything needed to call and interpret the response.

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 baseline is 3, but the description adds real meaning: keyword_id provenance ('from list_keywords') and app_id's effect of narrowing output to a single series. It also explains the date-window constraints that shape from/to beyond the schema's terse default notes.

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 precise verb+resource ('daily rank history of one tracked keyword, with one series per app that tracks it') and explicitly contrasts itself with the sibling get_app_score_history, which covers whole-app visibility rather than one keyword. An agent can select this tool without opening any 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?

Gives explicit routing: 'Pass keyword_id from list_keywords, and app_id to narrow the output to one app. For the visibility of a whole app rather than one keyword, use get_app_score_history.' This names both the prerequisite source for the required parameter and the alternative tool with its selecting condition.

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

Deploy Server

Other Tools