RealWorldAPIs

Find API for Task

find_api_for_task

Read-only

Find the best APIs for a natural-language physical-world task. Use this for open-ended task or outcome-based recommendations; use search_apis when you already know exact filters, get_api for one known API, or compare_apis for known candidates. Returns an authoritative canonical structured_results shortlist plus a best-effort AI comparison restricted to that shortlist. The canonical engine now applies Verified/High capability evidence before ranking: explicit hard requirements expressed with terms such as must, required, no or without can exclude a candidate only when verified evidence contradicts them. Unknown evidence remains eligible and is surfaced as uncertainty. requirements.mcp, openapi and auth are translated into explicit requirements; categories and capabilities remain task-shaping hints. free_tier and min_readiness are accepted for compatibility but are not hard filters.

Input Schema

TableJSON Schema

Name	Required	Description
`task`	Yes	Required natural-language goal or workflow, for example 'connect to a car and predict weather on the route'. Describe the desired outcome rather than naming a specific API.
`limit`	No	Backward-compatible parameter. The canonical browser-parity workflow always produces five structured candidates before the AI comparison, even when another value is supplied.
`requirements`	No	Optional task requirements appended before canonical ranking. categories and capabilities shape task intent. mcp=Yes, openapi=Yes and auth are expressed as hard task requirements and are evaluated against verified evidence; Unknown does not count as a confirmed contradiction and remains eligible with an uncertainty. free_tier and min_readiness are accepted for backward compatibility but are not hard filters.

Output Schema

TableJSON Schema

Name	Required	Description
`ai`	Yes
`name`	Yes
`task`	Yes
`method`	No
`timing_ms`	No
`ai_comparison`	No	Best-effort grounded explanation of only the structured_results candidates.
`snapshot_date`	No
`engine_version`	No
`coverage_status`	No
`effective_query`	No
`grounding_policy`	Yes
`source_endpoints`	No
`coverage_warnings`	No
`structured_results`	Yes	Canonical deterministic shortlist. This is the authoritative result set.
`compatibility_warnings`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedSep 30, 2026

changedInput schema / properties / requirements / description

Previous value: -"Optional compatibility hints appended to the task before canonical ranking. categories, capabilities, mcp, openapi and auth influence the effective query. free_tier and min_readiness are accepted for backward compatibility but are not hard filters; use search_apis when you need strict field filtering."New value: +"Optional task requirements appended before canonical ranking. categories and capabilities shape task intent. mcp=Yes, openapi=Yes and auth are expressed as hard task requirements and are evaluated against verified evidence; Unknown does not count as a confirmed contradiction and remains eligible with an uncertainty. free_tier and min_readiness are accepted for backward compatibility but are not hard filters."

changedInput schema / properties / requirements / properties / auth / description

Previous value: -"Preferred authentication method, appended to the effective task as a ranking hint."New value: +"Authentication requirement appended as an explicit task requirement. The canonical engine excludes only when the verified API authentication methods contradict it."

changedInput schema / properties / requirements / properties / mcp / description

Previous value: -"Compatibility hint for MCP support. Only Yes becomes an explicit 'Must support MCP' task hint; use search_apis for exact Yes/No/Unknown filtering."New value: +"When set to Yes, becomes an explicit 'Must support MCP' requirement. Verified No excludes; Unknown remains eligible with an uncertainty. Use search_apis for exact status filtering."

changedInput schema / properties / requirements / properties / openapi / description

Previous value: -"Compatibility hint for OpenAPI support. Only Yes becomes an explicit task hint; use search_apis for exact Yes/No/Unknown filtering."New value: +"When set to Yes, becomes an explicit OpenAPI requirement. Verified No excludes; Unknown remains eligible with an uncertainty. Use search_apis for exact status filtering."

Changed11 schema fields changedSep 27, 2026

addedInput schema / properties / limit / description

Added value: +"Backward-compatible parameter. The canonical browser-parity workflow always produces five structured candidates before the AI comparison, even when another value is supplied."

addedInput schema / properties / requirements / description

Added value: +"Optional compatibility hints appended to the task before canonical ranking. categories, capabilities, mcp, openapi and auth influence the effective query. free_tier and min_readiness are accepted for backward compatibility but are not hard filters; use search_apis when you need strict field filtering."

addedInput schema / properties / requirements / properties / auth / description

Added value: +"Preferred authentication method, appended to the effective task as a ranking hint."

addedInput schema / properties / requirements / properties / capabilities / description

Added value: +"Desired agent capability dimensions. These are appended as ranking hints, not strict filters."

addedInput schema / properties / requirements / properties / categories / description

Added value: +"Preferred catalog categories, such as Geospatial, Weather or Mobility. These are ranking hints, not strict filters."

addedInput schema / properties / requirements / properties / free_tier / description

Added value: +"Backward-compatible field only. The canonical recommendation engine does not currently hard-filter on free-tier availability."

addedInput schema / properties / requirements / properties / mcp / description

Added value: +"Compatibility hint for MCP support. Only Yes becomes an explicit 'Must support MCP' task hint; use search_apis for exact Yes/No/Unknown filtering."

addedInput schema / properties / requirements / properties / min_readiness / description

Added value: +"Backward-compatible field only. It does not hard-filter the canonical top five; use search_apis for a strict minimum readiness threshold."

addedInput schema / properties / requirements / properties / openapi / description

Added value: +"Compatibility hint for OpenAPI support. Only Yes becomes an explicit task hint; use search_apis for exact Yes/No/Unknown filtering."

changedInput schema / properties / task / description

Previous value: -"Natural-language physical-world API task."New value: +"Required natural-language goal or workflow, for example 'connect to a car and predict weather on the route'. Describe the desired outcome rather than naming a specific API."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "ai": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "ai_comparison": {
+      "additionalProperties": true,
+      "description": "Best-effort grounded explanation of only the structured_results candidates.",
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "compatibility_warnings": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "coverage_status": {
+      "type": "string"
+    },
+    "coverage_warnings": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "effective_query": {
+      "type": "string"
+    },
+    "engine_version": {
+      "type": "string"
+    },
+    "grounding_policy": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "method": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "snapshot_date": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "source_endpoints": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "structured_results": {
+      "description": "Canonical deterministic shortlist. This is the authoritative result set.",
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "task": {
+      "type": "string"
+    },
+    "timing_ms": {
+      "additionalProperties": true,
+      "type": "object"
+    }
+  },
+  "required": [
+    "name",
+    "task",
+    "structured_results",
+    "ai",
+    "grounding_policy"
+  ],
+  "type": "object"
+}

Changed4 schema fields changedSep 26, 2026

removedInput schema / properties / limit / description

Removed value: -"Accepted for backward compatibility. The canonical browser-parity engine always produces five structured candidates before AI comparison."

removedInput schema / properties / requirements / description

Removed value: -"Backward-compatible query hints. mcp/openapi/auth/categories/capabilities are translated into explicit natural-language requirements before the canonical browser engine runs. free_tier and min_readiness are accepted but are not hard filters in browser-parity mode."

changedInput schema / properties / task / description

Previous value: -"Natural-language description of the real-world API task."New value: +"Natural-language physical-world API task."

changedOutput schema / (root)

Previous value: -{
-  "properties": {
-    "ai": {
-      "type": "object"
-    },
-    "ai_comparison": {
-      "type": [
-        "object",
-        "null"
-      ]
-    },
-    "compatibility_warnings": {
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "coverage_status": {
-      "type": "string"
-    },
-    "coverage_warnings": {
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "effective_query": {
-      "type": "string"
-    },
-    "engine_version": {
-      "type": "string"
-    },
-    "grounding_policy": {
-      "type": "object"
-    },
-    "method": {
-      "type": "string"
-    },
-    "name": {
-      "type": "string"
-    },
-    "snapshot_date": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "source_endpoints": {
-      "type": "object"
-    },
-    "structured_results": {
-      "items": {
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "task": {
-      "type": "string"
-    },
-    "timing_ms": {
-      "type": "object"
-    }
-  },
-  "required": [
-    "name",
-    "engine_version",
-    "method",
-    "task",
-    "structured_results",
-    "ai",
-    "grounding_policy"
-  ],
-  "type": "object"
-}New value: +null

Changed1 schema field changedSep 25, 2026
- addedOutput schema / properties / timing_ms
```
Added value: +{
+  "type": "object"
+}
```

Changed31 schema fields changedSep 24, 2026

changedInput schema / properties / limit / default
```
Previous value: -3New value: +5
```

changedInput schema / properties / limit / description

Previous value: -"Maximum number of ranked recommendations to return."New value: +"Accepted for backward compatibility. The canonical browser-parity engine always produces five structured candidates before AI comparison."

changedInput schema / properties / requirements / description

Previous value: -"Canonical location for structured hard constraints. Do not put capabilities, mcp, openapi, auth, free_tier, category, or min_readiness at the top level."New value: +"Backward-compatible query hints. mcp/openapi/auth/categories/capabilities are translated into explicit natural-language requirements before the canonical browser engine runs. free_tier and min_readiness are accepted but are not hard filters in browser-parity mode."

removedInput schema / properties / requirements / properties / auth / description
```
Removed value: -"Required authentication method."
```

removedInput schema / properties / requirements / properties / capabilities / description

Removed value: -"All listed real-world capabilities must be true for an eligible API."

removedInput schema / properties / requirements / properties / categories / description

Removed value: -"Allowed RealWorldAPIs categories. Use only when category itself is a hard constraint."

removedInput schema / properties / requirements / properties / free_tier / description

Removed value: -"When true, only APIs audited as having a free tier remain eligible."

removedInput schema / properties / requirements / properties / mcp / description
```
Removed value: -"Set to Yes when MCP support is required."
```
removedInput schema / properties / requirements / properties / min_readiness / description
```
Removed value: -"Minimum audited Agent Readiness Score."
```
removedInput schema / properties / requirements / properties / openapi / description
```
Removed value: -"Set to Yes when OpenAPI support is required."
```

changedInput schema / properties / task / description

Previous value: -"Natural-language description of what the agent or application needs to do. State hard requirements explicitly, for example: 'must support MCP'."New value: +"Natural-language description of the real-world API task."

removedOutput schema / properties / agent_summary

Removed value: -{
-  "properties": {
-    "alternatives": {
-      "items": {
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "grounding_policy": {
-      "type": "object"
-    },
-    "presentation_guidance": {
-      "type": "string"
-    },
-    "top_pick": {
-      "type": [
-        "object",
-        "null"
-      ]
-    }
-  },
-  "type": "object"
-}

addedOutput schema / properties / ai
```
Added value: +{
+  "type": "object"
+}
```

addedOutput schema / properties / ai_comparison

Added value: +{
+  "type": [
+    "object",
+    "null"
+  ]
+}

removedOutput schema / properties / catalog_size
```
Removed value: -{
-  "type": "integer"
-}
```

removedOutput schema / properties / caveat

Removed value: -{
-  "type": "string"
-}

addedOutput schema / properties / compatibility_warnings

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / coverage_status
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / coverage_warnings

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / effective_query
```
Added value: +{
+  "type": "string"
+}
```
removedOutput schema / properties / eligible_count
```
Removed value: -{
-  "type": "integer"
-}
```
addedOutput schema / properties / grounding_policy
```
Added value: +{
+  "type": "object"
+}
```
removedOutput schema / properties / input_normalization
```
Removed value: -{
-  "type": "object"
-}
```
addedOutput schema / properties / method
```
Added value: +{
+  "type": "string"
+}
```

removedOutput schema / properties / recommendations

Removed value: -{
-  "items": {
-    "type": "object"
-  },
-  "type": "array"
-}

removedOutput schema / properties / requirements_applied
```
Removed value: -{
-  "type": "object"
-}
```
removedOutput schema / properties / requirements_detected
```
Removed value: -{
-  "type": "object"
-}
```

addedOutput schema / properties / snapshot_date

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / source_endpoints
```
Added value: +{
+  "type": "object"
+}
```

addedOutput schema / properties / structured_results

Added value: +{
+  "items": {
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "name",
-  "engine_version",
-  "task",
-  "catalog_size",
-  "eligible_count",
-  "agent_summary",
-  "recommendations",
-  "caveat"
-]New value: +[
+  "name",
+  "engine_version",
+  "method",
+  "task",
+  "structured_results",
+  "ai",
+  "grounding_policy"
+]

First observedSep 12, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare it as a read-only, non-idempotent lookup; the description adds the substantive behavior: Verified/High capability evidence gating, that unknown evidence stays eligible and is surfaced as uncertainty, that must/required/no/without only exclude on verified contradiction, and that free_tier/min_readiness are accepted but not hard filters. That is well beyond what annotations provide.

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?

The routing rule and the constraint on hard requirements are front-loaded and every sentence carries information. However, the requirements paragraph in the description restates much of what the individual property descriptions already say, adding some redundancy to an already dense block.

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?

Given an output schema exists, the description still usefully sketches the return shape (authoritative canonical structured_results shortlist plus a best-effort AI comparison scoped to that shortlist). Combined with the ranking/evidence rules and requirement semantics, an agent has everything needed to call and interpret it.

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 baseline is 3, but the description adds real semantics: it clarifies which requirements become hard task requirements (mcp=Yes, openapi=Yes, auth) versus ranking hints (categories, capabilities), and warns that limit is effectively pinned to five and free_tier/min_readiness do not filter. It mostly repeats the per-parameter schema text rather than adding a distinct layer, hence 4 rather than 5.

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 first sentence states a specific verb+resource+scope: 'Find the best APIs for a natural-language physical-world task.' It goes further and explicitly distinguishes itself from three siblings by name (search_apis, get_api, compare_apis), so an agent can route 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?

It gives an explicit selection rule: use this for open-ended/outcome-based recommendations, use search_apis for known exact filters, get_api for a single known API, compare_apis for known candidates. It also states per-field guidance ('Use search_apis for exact status filtering' and for a strict min_readiness threshold).

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

All RealWorldAPIs tools Inspect

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.

Find API for Task

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources