Lies die Spezifikation. Verstehe die API. Integriere mit Zuversicht.
Englisch | 繁體中文
apifable ist ein MCP-Server, der KI dabei hilft, APIs reibungsloser in TypeScript-Frontend-Projekte zu integrieren. Er macht es einfach, die API-Struktur zu erkunden, Endpunkte zu durchsuchen und TypeScript-Typen zu generieren, wodurch dein KI-Agent den Kontext erhält, den er für das Schreiben präziser Integrationscodes benötigt.
Related MCP server: openapi-mcp-proxy
📦 KI-bereiter API-Kontext — gib der KI die Struktur, die sie benötigt, um deine API zu verstehen und damit zu arbeiten
📘 OpenAPI 3.0 / 3.1 Unterstützung — funktioniert mit Standard-Spezifikationen als verlässliche Quelle der Wahrheit
🤖 MCP-Server für KI-Agenten — verbinde dich mit Claude, Cursor und Windsurf
🔍 API-Erkundungstools — durchsuche Endpunkte, suche nach Schlüsselwörtern und untersuche vollständige Request/Response-Details
🏷️ TypeScript-Typgenerierung — generiere TypeScript-Typdefinitionen, die direkt im Frontend-Code verwendet werden können
Führe apifable init aus, um deine Projektkonfiguration einzurichten:
npx apifable@latest initDies erstellt eine apifable.config.json in deinem Projektstammverzeichnis. Die Konfigurationsdatei sollte in die Versionsverwaltung aufgenommen werden, damit der Pfad zur Spezifikation mit deinem Team geteilt wird.
Nachdem der Befehl gestartet wurde, kannst du zwischen Manuelle Datei und Remote-URL wählen.
Verwende diesen Modus, wenn deine OpenAPI-Spezifikation bereits im Projekt vorhanden ist oder wenn du Spezifikationsaktualisierungen selbst verwalten möchtest.
init fragt nach dem lokalen Dateipfad, wie z. B. openapi.yaml.
Du musst deine OpenAPI-Spezifikation dann manuell an diesem Pfad ablegen. Wenn sich die Backend-API ändert, musst du diese Datei ebenfalls manuell aktualisieren.
Verwende diesen Modus, wenn deine OpenAPI-Spezifikation über eine stabile Remote-URL verfügbar ist, wie z. B. der OpenAPI-Spezifikations-Endpunkt, der von deiner Backend-API-Dokumentation bereitgestellt wird.
init fragt zuerst nach der Remote-URL, wie z. B. https://api.example.com/openapi.yaml, und dann nach dem lokalen Ausgabepfad, wie z. B. ./openapi.yaml.
[!NOTE] In diesem Modus fügt
initden heruntergeladenen lokalen Spezifikationspfad automatisch zu.gitignorehinzu, da die Datei dazu gedacht ist, von der Remote-Quelle aktualisiert zu werden.
Du kannst dann den folgenden Befehl ausführen, um die OpenAPI-Spezifikation von der Remote-URL auf deinen lokalen Pfad herunterzuladen (spec.url → spec.path). Wann immer sich die Spezifikation ändert, führe ihn einfach erneut aus, um sie zu aktualisieren:
npx apifable@latest fetchFür nicht sensible Header, die mit deinem Team geteilt werden können, füge spec.headers zur apifable.config.json hinzu:
{
"spec": {
"path": "openapi.yaml",
"url": "https://example.com/openapi.yaml",
"headers": {
"X-Api-Version": "2"
}
}
}Wenn das Herunterladen der Remote-OpenAPI-Spezifikation eine Authentifizierung erfordert (private API), speichere geheime Header in .apifable/auth.json. Diese Datei sollte nicht in die Versionsverwaltung aufgenommen werden:
{
"headers": {
"Authorization": "Bearer YOUR_SECRET_TOKEN"
}
}Sowohl apifable.config.json als auch .apifable/auth.json unterstützen die ${ENV_VAR}-Syntax in Header-Werten.
{
"headers": {
"Authorization": "Bearer ${MY_API_KEY}"
}
}.apifable/auth.json Header (überschreibt gleichnamige Schlüssel)
apifable.config.json spec.headers
Füge Folgendes zu deiner .mcp.json hinzu:
{
"mcpServers": {
"apifable": {
"command": "npx",
"args": ["-y", "apifable@latest", "mcp"]
}
}
}Für andere KI-Agenten wie Cursor und Windsurf kannst du denselben Ansatz verfolgen, um apifable als MCP-Server zu konfigurieren.
Hier sind einige Beispiel-Prompts, die du verwenden kannst, um APIs zu erkunden und Funktionen zu erstellen.
List all APIsShow me APIs related to postsList APIs under the Post tagShow me the API details for post commentsShow me the API details for GET /posts/{id}/commentsShow me the API details for postCommentsImplement the post comments feature
Post page: src/pages/posts/[id].tsx
Related APIs:
- GET /posts/{id}/comments (list post comments)
- POST /posts/{id}/comments (create a post comment)[!TIP] Wenn du einen Prompt zum Erstellen einer Funktion schreibst, füge relevanten Kontext hinzu: Seitenpfade, Komponentenorte, zugehörige APIs sowie alle Muster oder Beispiele, denen gefolgt werden soll.
Füge Folgendes zur AGENTS.md deines Projekts hinzu, um KI-Agenten dabei zu helfen, apifable effektiver zu nutzen:
## API Integration (apifable)
- Always use `get_endpoint` to verify the exact path, method, and parameters before writing integration code. Never assume.
- When presenting endpoint list data from apifable tools, display exactly these columns in order: `Method` (Uppercase), `Path`, `Summary`. Keep all values verbatim, including summary prefixes like `[ 32 - 001 ]`. Do not omit, rename, paraphrase, or add extra columns.
- When saving generated types, store them under `src/types/` and name files by domain (e.g., `src/types/auth.ts`, `src/types/user.ts`), not by OpenAPI tag names.Das Obige ist ein empfohlener Ausgangspunkt. Fühle dich frei, die Spalten der Endpunktliste und den Pfad zum Typen-Ordner an dein Projekt anzupassen.
get_spec_infoGibt den API-Titel, die Version, die Beschreibung, die Server und alle Tags mit ihren Endpunkt-Anzahlen zurück. Beginne hier, um die Form einer unbekannten Spezifikation zu verstehen.
list_endpoints_by_tagEingaben:
tag (string): Der Tag-Name zum Filtern
limit (number, optional): Maximale Anzahl der zurückzugebenden Endpunkte
offset (number, optional): Anzahl der zu überspringenden Endpunkte (Standard: 0)
Gibt alle Endpunkte zurück, die zum angegebenen Tag gehören. Die Antwort enthält total, offset und hasMore-Felder für die Paginierung. Enthält eine Warnung, wenn die Ergebnisse 30 Elemente überschreiten und kein limit angegeben ist.
search_endpointsEingaben:
query (string): Schlüsselwort für die Suche
tag (string, optional): Suche auf einen bestimmten Tag beschränken
limit (number, optional): Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 10)
Schlüsselwortsuche über operationId, Pfad, Zusammenfassung und Beschreibung. Die Ergebnisse werden nach Relevanz sortiert. Wenn keine exakten Übereinstimmungen gefunden werden, wird automatisch auf eine Fuzzy-Suche zurückgegriffen. Die Antwort enthält ein matchType-Feld ("exact" oder "fuzzy"); Fuzzy-Ergebnisse enthalten zusätzlich ein score-Feld pro Ergebnis.
get_endpointEingaben (wähle eine):
method (string) + path (string): HTTP-Methode und Endpunktpfad (z. B. get + /users/{id})
operationId (string): Operations-ID (z. B. listUsers)
Gibt das vollständige Endpunkt-Objekt zurück, einschließlich Parametern, requestBody und Antworten, wobei unterstützte interne Komponenten-$refs inline aufgelöst werden.
search_schemasEingaben:
query (string): Schlüsselwort für die Suche
limit (number, optional): Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 10)
Schlüsselwortsuche über Schemaname und Beschreibung. Die Ergebnisse werden nach Relevanz sortiert. Wenn keine exakten Übereinstimmungen gefunden werden, wird automatisch auf eine Fuzzy-Suche zurückgegriffen. Die Antwort enthält ein matchType-Feld ("exact" oder "fuzzy"); Fuzzy-Ergebnisse enthalten zusätzlich ein score-Feld pro Ergebnis. Leere Ergebnisse können auch ein message-Feld mit Anleitungen für den nächsten Schritt enthalten.
get_schemaEingaben:
name (string): Schemaname aus components/schemas
Gibt das vollständige Schema mit aufgelösten unterstützten internen Komponenten-$refs zurück.
get_typesEingaben (wähle einen Modus):
schemas (string[]): Array von Schemanamen aus components/schemas
method (string) + path (string): HTTP-Methode und Endpunktpfad
operationId (string): Operations-ID (z. B. listUsers)
Generiert in sich geschlossene TypeScript-Deklarationen als Codetext. Im Endpunkt-Modus folgt es unterstützten internen Komponenten-$refs, bevor Schema-Abhängigkeiten gesammelt werden. Es enthält automatisch transitive Abhängigkeiten und keine Import-Anweisungen.
Modus-Regeln:
Verwende genau einen Modus pro Aufruf: schemas, method + path oder operationId
Mische keine Modi im selben Aufruf
Externe $refs (z. B. Verweise auf andere Dateien oder URLs) werden nicht unterstützt.
OpenAPI 2.0 (Swagger) wird nicht unterstützt. Nur OpenAPI 3.0 und 3.1 Spezifikationen werden unterstützt.
Wenn du denkst, dass dieses Paket dir geholfen hat, ziehe bitte in Betracht, Sponsor zu werden, um meine Arbeit zu unterstützen~ und dein Avatar wird auf meinen Hauptprojekten sichtbar sein.
@reapi/mcp-openapi — für die anfängliche Inspiration
Get full details of a specific endpoint including parameters, request body, responses, and security requirements. Supported internal component $refs are resolved inline. Provide either "method" + "path" or "operationId". Use get_types to get TypeScript type declarations for the endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Endpoint path (e.g. /users/{id}) | |
| method | No | HTTP method (e.g. get, post, put, delete) | |
| operationId | No | Operation ID to look up (e.g. listUsers) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that supported internal component $refs are resolved inline, which is a non-obvious behavioral trait, and lists the response contents. This goes beyond a simple 'gets details' and is transparent about processing.
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?
Three sentences with no redundancy: the first states purpose, the second adds a key behavioral detail, and the third gives usage and an alternative. Purpose is front-loaded, and every sentence earns its place.
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?
For a simple get tool with no output schema and no required parameters, the description covers the return contents, the resolution behavior, and the input rules. It also points to a sibling for related needs. Nothing the agent needs to call it correctly is missing.
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 coverage is 100% with each parameter already described. The description adds value by specifying the mutual exclusivity (either method+path or operationId), which is not explicit in the schema. This relationship is critical for correct invocation, so the description compensates beyond the schema baseline.
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 clearly states it 'Get full details of a specific endpoint' and enumerates the exact contents (parameters, request body, responses, security requirements). It distinguishes this from sibling list/search tools by targeting a single endpoint, and also differentiates from get_types by specifying the type-declaration role.
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 explicitly instructs the caller to provide either 'method' + 'path' or 'operationId', which is a precise usage rule. It also names the alternative tool get_types for TypeScript declarations, giving clear routing criteria. This satisfies the when/alternative requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific schema from components/schemas by name. Supported internal component $refs are resolved inline. Use get_types to convert schemas to TypeScript type declarations.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Schema name (e.g. User, CreateOrderRequest) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose a key behavioral trait: internal $refs are resolved inline. This goes beyond the schema. However, it doesn't mention error handling, permissions, or what happens when the schema is not found, which would add confidence for an agent.
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 compact sentences. The first states the core function and the inline-ref detail; the second gives a clear pointer to a related tool. No fluff, information density is high and front-loaded.
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?
For a simple one-parameter get operation with no output schema, the description covers the essential intent, the ref-resolution behavior, and a related alternative. It doesn't specify return shape or error cases, but those are less critical given the tool's simplicity. Slight gap in detail about failure modes prevents a 5.
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 100% for the only parameter ('name' is described with an example). The description's phrase 'by name' aligns with the param but adds no extra semantic detail beyond what the schema already provides. Baseline 3 is appropriate.
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 states a specific verb ('Get') and resource ('a specific schema from components/schemas by name'), and distinguishes itself from sibling tools like 'get_types' by mentioning conversion. It is clear which tool to use when you need a single named schema.
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 explicitly tells the agent to use 'get_types' for TypeScript conversion, which clarifies a distinct use case. However, it does not explicitly contrast with 'search_schemas' (e.g., 'use search_schemas if you don't know the name'), so the 'when not to use' guidance is only implied. Still, the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get general information about the OpenAPI spec: title, version, description, servers, security schemes, and available tags with endpoint counts. Start here to understand an unfamiliar API. Then use list_endpoints_by_tag or search_endpoints to explore specific areas.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description implies a read-only operation without side effects; no annotations are provided, but the description adequately conveys the tool's behavior. Could potentially mention that it returns summary data, but overall transparent.
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: first states purpose and contents, second gives usage guidance. Efficient, front-loaded, and no wasted words.
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?
For a parameterless tool with no output schema, the description fully explains what it returns (title, version, description, servers, security schemes, tags with counts) and how to use it.
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?
No parameters exist, so schema coverage is 100%. The description adds no parameter-specific info, but given no parameters, the baseline of 4 is appropriate.
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?
Clearly states it retrieves general information about the OpenAPI spec and lists specific items (title, version, etc.). Distinguishes from siblings by positioning it as the starting point and suggesting exploration tools like list_endpoints_by_tag and search_endpoints.
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?
Explicitly advises to 'Start here to understand an unfamiliar API' and then use list_endpoints_by_tag or search_endpoints for further exploration, providing clear when-to-use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate self-contained TypeScript type declarations for specified schemas or for all schemas used by a specific endpoint. Endpoint mode follows supported internal component $refs before collecting schema dependencies. Provide exactly one of: "schemas" (array of schema names), "method" + "path" (endpoint), or "operationId". Transitive dependencies are included automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Endpoint path for endpoint mode (e.g. /users/{id}) | |
| method | No | HTTP method for endpoint mode (e.g. get, post) | |
| schemas | No | Array of schema names from components/schemas (e.g. ["User", "Address"]) | |
| operationId | No | Operation ID to generate types for (e.g. listUsers) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that transitive dependencies are included automatically and that endpoint mode follows internal $refs, which is valuable. However, it doesn't mention side effects (though generation is likely read-only) or error behavior, leaving some transparency gaps.
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?
The description is a single dense paragraph that front-loads the purpose, then explains the modes, and ends with the dependency behavior. Every sentence contributes value; no filler or redundancy.
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?
For a type-generation tool with no output schema, the description clearly states what it produces (self-contained TypeScript declarations) and how to invoke it. It lacks details about output format (e.g., string vs. file) and error cases, but these are minor given the simplicity of the tool.
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?
The schema describes all four parameters fully (100% coverage), but the description adds critical semantics: the mutual exclusivity constraint and the meaning of each mode (schemas vs. method+path vs. operationId). This goes beyond the schema's individual parameter descriptions.
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 states a specific action (generate self-contained TypeScript type declarations) with a clear resource (schemas or endpoint-used schemas). It distinguishes from siblings like get_schema (which returns a single schema definition) and search_schemas (which searches), making the purpose unambiguous.
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 gives explicit input rules: 'Provide exactly one of: schemas, method+path, or operationId', and explains endpoint mode follows $refs. It doesn't explicitly contrast with alternatives, but the uniqueness of the tool (generating types vs. listing/searching) makes the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all endpoints belonging to a specific tag. Use get_spec_info first to see available tags. Supports pagination via limit and offset. Then use get_endpoint to inspect a specific endpoint in detail.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | The tag name to filter endpoints by | |
| limit | No | Maximum number of endpoints to return | |
| offset | No | Number of endpoints to skip (default: 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. 'List' implies a read-only operation and the suggestion to use get_endpoint for details implies response summaries, but auth requirements, response shape, and pagination edge cases are not disclosed. This is minimal but not misleading.
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?
Three sentences front-load the core purpose and follow with brief, useful workflow steps. The pagination mention is slightly redundant with the schema, but the overall structure is efficient with no fluff.
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?
For a simple list tool with no output schema and no annotations, the description covers the core workflow and pagination, but leaves the return format and error behavior unstated. An agent could call it correctly, but would need to discover response details from a sample call rather than the description.
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 100%, so all three parameters are already documented. The description only restates limit/offset as pagination support, adding no new meaning beyond what the schema provides. Baseline 3 applies.
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 clearly states the action ('List') and resource ('endpoints filtered by tag'). It is specific about the filter dimension, but does not explicitly contrast with sibling search_endpoints, so an agent must infer the distinction from the tag-based wording.
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?
Provides explicit workflow guidance: call get_spec_info first to discover valid tags and use get_endpoint afterward for detail. It gives a clear context for when this tool fits, but does not state when to prefer search_endpoints or when not to use this tool, so exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search endpoints by keyword across operationId, path, summary, and description. Results are ranked by relevance. If no exact matches are found, automatically falls back to fuzzy search. The response includes a matchType field ("exact" or "fuzzy"); fuzzy results also include a score field per result. After finding the target endpoint, use get_endpoint for full details or get_types for TypeScript types.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Optional tag to filter results | |
| limit | No | Maximum number of results (default: 10) | |
| query | Yes | Search keyword |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the fallback behavior, the matchType field, and the score field for fuzzy results. It doesn't mention pagination or error behavior, but for a read-only search tool, the described behavior is transparent enough. The absence of annotations is compensated by this explicit behavioral detail.
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?
The description is a few sentences, front-loaded with the primary action and scope. It covers the fallback, output fields, and follow-up tools without unnecessary filler. It is concise and well-structured, earning a score above average.
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?
Given the lack of an output schema, the description provides essential return information (matchType, score) and suggests next steps. It covers the core search behavior and result format. While it doesn't address edge cases like no results or error conditions, for a search tool with simple parameters, the description is sufficiently complete for an agent to use it correctly.
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?
The input schema already documents all three parameters (tag, limit, query) with descriptions, so schema coverage is 100%. The tool description adds context about result ranking and matchType/score fields, but these are about output, not parameter semantics. It doesn't elaborate on parameter usage beyond what the schema provides, so a baseline of 3 is appropriate.
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 states a specific verb (search) and resource (endpoints), and clarifies the scope (operationId, path, summary, description). It also mentions ranking by relevance and the fallback to fuzzy search, which distinguishes it from sibling tools like list_endpoints_by_tag and get_endpoint. The purpose is unambiguous and clearly differentiates from alternatives.
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?
The description provides explicit guidance on when to use this tool and what to do next: it mentions the automatic fallback to fuzzy search and directs the user to get_endpoint or get_types after finding the target. It doesn't explicitly state when not to use it, but the follow-up instructions and the optional tag filter give enough context for an agent to decide when this is the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search schemas by keyword across schema name and description. Results are ranked by relevance. If no exact matches are found, automatically falls back to fuzzy search. Empty results may include a guidance message suggesting next steps. Use get_schema to inspect a specific schema in detail.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default: 10) | |
| query | Yes | Search keyword |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers: results are relevance-ranked, there is an automatic fuzzy-search fallback when no exact matches exist, and empty results may include a guidance message suggesting next steps. These are non-obvious behaviors an agent needs to interpret results correctly. Minor gaps are the lack of an explicit read-only confirmation and any pagination/result-cap behavior beyond what the schema's limit parameter already states.
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?
Five sentences, each earning its place: core purpose, ranking behavior, fuzzy fallback, empty-result guidance, and sibling routing. The description is front-loaded with the primary purpose and contains zero redundancy or filler. It is compact while carrying all essential information.
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?
For a simple 2-parameter search tool with no output schema and no annotations, the description covers search scope, relevance ranking, fuzzy fallback, empty-result behavior, and the next-step route to get_schema. The one gap is that no output schema exists and the description does not sketch the result shape, but for a keyword search tool this is a minor omission given the tool's simplicity.
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 100%, so both query and limit are already documented in the schema with meaningful descriptions. The tool description adds contextual enrichment (query matches against name and description, fuzzy fallback behavior) but no parameter-level syntax or format detail beyond what the schema provides. The baseline 3 applies because the schema does the heavy lifting.
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 opens with a specific verb+resource+scope: 'Search schemas by keyword across schema name and description.' It clearly distinguishes from sibling get_schema by naming it as the inspection path, and the scope wording ('schemas... across schema name and description') implicitly differentiates from search_endpoints. An agent can tell what this tool does without opening the schema.
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?
The description gives an explicit routing instruction: 'Use get_schema to inspect a specific schema in detail,' which tells the agent when this search tool is the wrong choice. The fallback and relevance-ranking notes clarify the trustworthiness of results. However, it never explicitly names search_endpoints as the alternative for endpoint search, leaving that sibling distinction implicit rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.2.0get_endpoint1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"get_schema1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"get_types1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"list_endpoints_by_tag1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"search_endpoints1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"search_schemas1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"v1.1.1get_endpointget_schemaget_spec_infoget_typeslist_endpoints_by_tagsearch_endpointssearch_schemasScored across 7 tools
Each tool targets a distinct action: spec overview, endpoint search/list/detail, schema search/detail, and TypeScript generation. No two tools overlap in purpose, and cross-references between them make selection clear.
All tools use a consistent lowercase snake_case verb_noun pattern: get_, search_, and list_. Even the longer list_endpoints_by_tag follows the same predictable convention.
Seven tools is well-scoped for an OpenAPI exploration and type-generation server. Each tool fills a distinct role without redundancy or bloat.
The surface covers the core exploration workflow well: discover spec info, find endpoints/schemas, inspect details, and generate TypeScript types. Minor gaps exist such as no way to list all schemas or all endpoints globally, but these are workable through tags and search.
MCP server for AI access to Swagger by SmartBear.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.