Skip to main content
Glama

apis-io

by io.apis
OverviewDiscussionsAdmin

find_ratings

Read-only

Ranked ratings leaderboard — filter by band, score range, trend, or facet threshold. Sort by composite (default), delta (biggest gainers), or any quality facet (governance, security, …) to rank providers by that dimension. Priced per result — $0.005 per request plus $0.0002 per record returned (less past 100), capped at $0.50 a request, under pay-as-you-go; included in Understanding and Influence. Estimate first at /api/v1/prices/estimate. See apis://prices.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
bandNo
pageNo
sortNoLeaderboard order; default composite.
tagsNo
facetNo
limitNo
trendNo
contextNoOptional: why you are asking. One sentence — the task you are trying to complete, or what you expect to get back. Never included in the answer and never used to rank; it is read only when a result turns out to be wrong, which is when knowing the intent is what makes the report actionable.
max_scoreNoOnly ratings at or below this composite. Pair with min_score for a range.
min_facetNo
min_scoreNo
providersNoRestrict to these provider slugs — the ratings of a named set.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / sort / enum
      Previous value: -[
-  "composite",
-  "delta",
-  "discoverability",
-  "contract_quality",
-  "governance",
-  "operational_transparency",
-  "developer_ergonomics",
-  "commercial_clarity"
-]New value: +[
+  "composite",
+  "delta",
+  "discoverability",
+  "contract_quality",
+  "contract_governance",
+  "operational_transparency",
+  "developer_ergonomics",
+  "access_clarity",
+  "governance",
+  "commercial_clarity"
+]
  2. Changed2 schema fields changed
    • addedInput schema / properties / max_score
      Added value: +{
+  "description": "Only ratings at or below this composite. Pair with min_score for a range.",
+  "type": "number"
+}
    • addedInput schema / properties / providers
      Added value: +{
+  "description": "Restrict to these provider slugs — the ratings of a named set.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
  3. Changed1 schema field changed
    • addedInput schema / properties / context
      Added value: +{
+  "description": "Optional: why you are asking. One sentence — the task you are trying to complete, or what you expect to get back. Never included in the answer and never used to rank; it is read only when a result turns out to be wrong, which is when knowing the intent is what makes the report actionable.",
+  "type": "string"
+}
  4. Changed1 schema field changed
    • addedInput schema / properties / sort
      Added value: +{
+  "description": "Leaderboard order; default composite.",
+  "enum": [
+    "composite",
+    "delta",
+    "discoverability",
+    "contract_quality",
+    "governance",
+    "operational_transparency",
+    "developer_ergonomics",
+    "commercial_clarity"
+  ],
+  "type": "string"
+}
  5. First observed

TDQS

A4.1/5.0
Behavior4/5

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

The description adds pricing behavior (per-request, per-record, cap, plan inclusion) and explains sorting semantics ('delta' = biggest gainers), which is beyond what readOnlyHint alone provides. It does not mention response format or rate limits, but the annotation already covers operational safety.

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

Conciseness5/5

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

Three sentences, each with distinct content: purpose/filters, sort modes, and pricing. The purpose is front-loaded, and pricing is placed last. No filler.

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

Completeness3/5

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

For a 12-parameter tool with no output schema, the description covers the main filtering and sorting dimensions but leaves several params (trend values, facet threshold mechanics, pagination limits) implicit. The pricing and estimate note is helpful, but not all agent-relevant details are present.

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 only 33%, so the description carries more burden. It maps band, score range (min/max), trend, facet threshold, and sort options, but leaves page, limit, tags, min_facet, and context (some of which have schema descriptions) without further explanation. It adds value but does not fully compensate for the low schema coverage.

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 opens with 'Ranked ratings leaderboard' and enumerates filters and sort dimensions, clearly identifying a specific verb (find/rank), resource (ratings), and scope. It distinguishes itself from siblings like find_rating_movers by emphasizing leaderboard ranking and 'delta (biggest gainers)', though it does not explicitly name alternatives.

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?

It gives clear context—use this for ranked, filterable rating leaderboards, with sort options. It also advises 'Estimate first at /api/v1/prices/estimate', which is a usage directive about cost. It does not explicitly state when not to use it or name sibling tools, so it stops short of a 5.

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

All apis-io 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