Get the ranking trend

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

Annotations only declare readOnlyHint=true, so the description earns credit for adding the ordering guarantee (oldest first), the scope of returned data (only completed grids of a matching map), and the cost profile ("Free"). It omits failure behavior (no completed grids, mismatched identifiers) and how the limit parameter truncates results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the return shape and followed by the invocation recipe and cost note. No filler, no restatement of the name or title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does the work of explaining the return payload (ordered grid history plus first-to-last change), which is the key missing piece elsewhere. Gaps remain around pagination via limit and edge cases such as no prior grids for a keyword.

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

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

Schema description coverage is 0%, so the description carries the burden and largely does: it explains that grid_id and the place_id/keyword pair are alternative selection modes and that the latest grid determines map format. The limit parameter is never mentioned, leaving one of four parameters undocumented anywhere.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource and its contents: the ranking evolution of a listing for a keyword across every completed grid of the same map, plus the delta between first and last. An agent knows exactly what it gets back, though no sibling (get_grid, list_grids) is named to sharpen the boundary between this and those tools.

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

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

It states the two invocation paths clearly (grid_id alone, or place_id + keyword where the latest grid sets the format) and flags the operation as free, which matters given credit-consuming siblings like estimate_grid and get_balance. It stops short of naming alternatives or stating when-not to use this tool.

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