apis-io

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. Each row also carries agent_readiness {score, band} and front_door_ai {band, band_label, score} — the two standalone layers, never part of the composite. 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

Name	Required	Description
`band`	No	Rating bands: exemplar, strong, developing, thin, minimal, e.g. ["strong","exemplar"].
`page`	No	Page number, 1-based (default 1).
`sort`	No	Leaderboard order; default composite. agent_readiness and front_door_ai rank the two standalone layers; providers with no reading sort last.
`tags`	No	Tag slugs the provider carries, e.g. ["payments"].
`facet`	No	Facet to threshold with min_facet: discoverability, contract_quality, contract_governance, operational_transparency, developer_ergonomics, access_clarity.
`limit`	No	Results per page, 1-100 (default 25).
`trend`	No	Week-over-week movement: "rising" (+5 or more), "falling" (-5 or more) or "flat" (within 5).
`context`	No	Optional: one sentence on why you are asking. Never used to rank; read only if a result is wrong.
`max_score`	No	Only ratings at or below this composite. Pair with min_score for a range.
`min_facet`	No	Minimum score on `facet` (0-100); ignored without `facet`. E.g. 70.
`min_score`	No	Minimum Kin Score composite (0-100), e.g. 60.
`providers`	No	Restrict to these provider slugs — the ratings of a named set.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 28, 2026

changedInput schema / properties / sort / description

Previous value: -"Leaderboard order; default composite."New value: +"Leaderboard order; default composite. agent_readiness and front_door_ai rank the two standalone layers; providers with no reading sort last."

changedInput schema / properties / sort / enum

Previous value: -[
-  "composite",
-  "delta",
-  "discoverability",
-  "contract_quality",
-  "contract_governance",
-  "operational_transparency",
-  "developer_ergonomics",
-  "access_clarity",
-  "governance",
-  "commercial_clarity"
-]New value: +[
+  "composite",
+  "delta",
+  "agent_readiness",
+  "front_door_ai",
+  "discoverability",
+  "contract_quality",
+  "contract_governance",
+  "operational_transparency",
+  "developer_ergonomics",
+  "access_clarity",
+  "governance",
+  "commercial_clarity"
+]

Changed3 schema fields changedOct 20, 2026

changedInput schema / properties / context / description

Previous value: -"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."New value: +"Optional: one sentence on why you are asking. Never used to rank; read only if a result is wrong."

changedInput schema / properties / min_score / description

Previous value: -"Only providers whose Kin Score composite is at or above this, 0-100, e.g. 60."New value: +"Minimum Kin Score composite (0-100), e.g. 60."

changedInput schema / properties / page / description

Previous value: -"Page number, 1-based (default 1). Use with `limit` to walk a long list."New value: +"Page number, 1-based (default 1)."

Changed8 schema fields changedOct 20, 2026

addedInput schema / properties / band / description

Added value: +"Rating bands: exemplar, strong, developing, thin, minimal, e.g. [\"strong\",\"exemplar\"]."

addedInput schema / properties / facet / description

Added value: +"Facet to threshold with min_facet: discoverability, contract_quality, contract_governance, operational_transparency, developer_ergonomics, access_clarity."

addedInput schema / properties / limit / description

Added value: +"Results per page, 1-100 (default 25)."

addedInput schema / properties / min_facet / description

Added value: +"Minimum score on `facet` (0-100); ignored without `facet`. E.g. 70."

addedInput schema / properties / min_score / description

Added value: +"Only providers whose Kin Score composite is at or above this, 0-100, e.g. 60."

addedInput schema / properties / page / description

Added value: +"Page number, 1-based (default 1). Use with `limit` to walk a long list."

addedInput schema / properties / tags / description

Added value: +"Tag slugs the provider carries, e.g. [\"payments\"]."

addedInput schema / properties / trend / description

Added value: +"Week-over-week movement: \"rising\" (+5 or more), \"falling\" (-5 or more) or \"flat\" (within 5)."

Changed1 schema field changedSep 12, 2026

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"
+]

Changed2 schema fields changedSep 4, 2026

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"
+}

Changed1 schema field changedAug 27, 2026

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"
+}

Changed1 schema field changedJul 16, 2026

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"
+}

First observedJun 29, 2026

TDQS

A3.9/5.0

Behavior4/5

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

With readOnlyHint/openWorldHint already covering safety, the description adds genuinely new behavior: per-result pricing with tiers and a $0.50 cap, plan inclusion, and the key data-model fact that agent_readiness and front_door_ai are standalone layers never folded into the composite. It does not cover pagination limits or total-count behavior.

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 purpose and filter/sort semantics before the pricing block, which is dense but earns its place for a metered tool. The pricing sentence is long and the pointer to apis://prices is slightly redundant with the estimate endpoint mention.

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?

For a 12-param, no-required-param read tool with no output schema, the description still documents the shape of returned rows and the layered scoring model, which is exactly what the schema cannot convey. Filtering, sorting, cost, and row composition are all covered.

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 the baseline is 3, and the description adds real meaning beyond it: it explains delta as gainers, that facet sorting ranks by that dimension, the filter axes as a group, and that `context` is never used for ranking. It doesn't disambiguate min_score versus min_facet interaction beyond what the schema already says.

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

Purpose4/5

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

Opens with a specific verb+resource ("Ranked ratings leaderboard") and states the filtering axes and sort modes, so an agent immediately knows this returns a ranked provider list. It doesn't name a sibling tool explicitly, so the boundary with find_rating_movers (delta) and find_providers is left to inference.

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

Usage Guidelines3/5

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

Usage context is implied ("delta (biggest gainers)" versus composite default; "Estimate first" before calling) but there is no explicit when-to-use/when-not statement or named alternative. The pricing pre-flight instruction is the strongest guidance offered.

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

All apis-io tools Inspect

Try in Browser

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?