Читайте спецификацию. Понимайте API. Интегрируйте с уверенностью.
English | 繁體中文
apifable — это MCP-сервер, который помогает AI более плавно интегрировать API в проекты на TypeScript. Он упрощает изучение структуры API, поиск эндпоинтов и генерацию типов TypeScript, предоставляя вашему AI-агенту контекст, необходимый для написания точного кода интеграции.
Related MCP server: openapi-mcp-proxy
📦 Контекст API, готовый для AI — предоставьте AI структуру, необходимую для понимания и работы с вашим API
📘 Поддержка OpenAPI 3.0 / 3.1 — работает со стандартными спецификациями как с надежным источником истины
🤖 MCP-сервер для AI-агентов — подключайтесь к Claude, Cursor и Windsurf
🔍 Инструменты исследования API — просматривайте эндпоинты, ищите по ключевым словам и изучайте полные детали запросов/ответов
🏷️ Генерация типов TypeScript — создавайте определения типов TypeScript, готовые к использованию в коде фронтенда
Запустите apifable init для настройки конфигурации вашего проекта:
npx apifable@latest initЭто создаст файл apifable.config.json в корне вашего проекта. Файл конфигурации следует добавить в систему контроля версий, чтобы путь к спецификации был доступен вашей команде.
После запуска команды вы сможете выбрать между Локальным файлом и Удаленным URL.
Используйте этот режим, если ваша спецификация OpenAPI уже находится в проекте или если вы хотите управлять обновлениями спецификации самостоятельно.
init запросит путь к локальному файлу, например openapi.yaml.
Затем вам нужно будет вручную разместить спецификацию OpenAPI по этому пути. При изменении бэкенд-API вам также нужно будет обновлять этот файл вручную.
Используйте этот режим, если ваша спецификация OpenAPI доступна по стабильному удаленному URL, например, через эндпоинт спецификации OpenAPI, предоставляемый документацией вашего бэкенд-API.
init сначала запросит удаленный URL, например https://api.example.com/openapi.yaml, а затем запросит путь для локального сохранения, например ./openapi.yaml.
[!NOTE] В этом режиме
initтакже автоматически добавляет путь к загруженной локальной спецификации в.gitignore, так как файл предназначен для обновления из удаленного источника.
Затем вы можете выполнить следующую команду, чтобы загрузить спецификацию OpenAPI с удаленного URL по вашему локальному пути (spec.url → spec.path). Всякий раз, когда спецификация меняется, просто запустите её снова для обновления:
npx apifable@latest fetchДля неконфиденциальных заголовков, которыми можно поделиться с командой, добавьте spec.headers в apifable.config.json:
{
"spec": {
"path": "openapi.yaml",
"url": "https://example.com/openapi.yaml",
"headers": {
"X-Api-Version": "2"
}
}
}Если для загрузки удаленной спецификации OpenAPI требуется аутентификация (приватный API), храните секретные заголовки в .apifable/auth.json. Этот файл не должен добавляться в систему контроля версий:
{
"headers": {
"Authorization": "Bearer YOUR_SECRET_TOKEN"
}
}И apifable.config.json, и .apifable/auth.json поддерживают синтаксис ${ENV_VAR} в значениях заголовков.
{
"headers": {
"Authorization": "Bearer ${MY_API_KEY}"
}
}Заголовки из .apifable/auth.json (переопределяют ключи с тем же именем)
spec.headers из apifable.config.json
Добавьте следующее в ваш .mcp.json:
{
"mcpServers": {
"apifable": {
"command": "npx",
"args": ["-y", "apifable@latest", "mcp"]
}
}
}Для других AI-агентов, таких как Cursor и Windsurf, вы можете следовать тому же подходу для настройки apifable в качестве MCP-сервера.
Вот несколько примеров промптов, которые вы можете использовать для изучения API и создания функций.
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] При написании промпта для создания функции включите соответствующий контекст: пути к страницам, расположение компонентов, связанные API, а также любые шаблоны или примеры, которым нужно следовать.
Добавьте следующее в файл AGENTS.md вашего проекта, чтобы помочь AI-агентам более эффективно использовать apifable:
## 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.Вышеприведенное является рекомендуемой отправной точкой. Не стесняйтесь настраивать столбцы списка эндпоинтов и путь к папке с типами в соответствии с вашим проектом.
get_spec_infoВозвращает название API, версию, описание, серверы и все теги с количеством эндпоинтов. Начните отсюда, чтобы понять структуру незнакомой спецификации.
list_endpoints_by_tagВходные данные:
tag (строка): Имя тега для фильтрации
limit (число, опционально): Максимальное количество эндпоинтов для возврата
offset (число, опционально): Количество эндпоинтов для пропуска (по умолчанию: 0)
Возвращает все эндпоинты, принадлежащие заданному тегу. Ответ включает поля total, offset и hasMore для пагинации. Включает предупреждение, если результаты превышают 30 элементов, а limit не указан.
search_endpointsВходные данные:
query (строка): Ключевое слово для поиска
tag (строка, опционально): Ограничить поиск определенным тегом
limit (число, опционально): Максимальное количество результатов для возврата (по умолчанию: 10)
Поиск по ключевым словам в operationId, пути, сводке и описании. Результаты ранжируются по релевантности. Если точных совпадений не найдено, автоматически переключается на нечеткий поиск. Ответ включает поле matchType ("exact" или "fuzzy"); нечеткие результаты также включают поле score для каждого результата.
get_endpointВходные данные (выберите одно):
method (строка) + path (строка): HTTP-метод и путь эндпоинта (например, get + /users/{id})
operationId (строка): ID операции (например, listUsers)
Возвращает полный объект эндпоинта, включая параметры, requestBody и ответы, с разрешенными внутренними компонентами $ref.
search_schemasВходные данные:
query (строка): Ключевое слово для поиска
limit (число, опционально): Максимальное количество результатов для возврата (по умолчанию: 10)
Поиск по ключевым словам в имени схемы и описании. Результаты ранжируются по релевантности. Если точных совпадений не найдено, автоматически переключается на нечеткий поиск. Ответ включает поле matchType ("exact" или "fuzzy"); нечеткие результаты также включают поле score для каждого результата. Пустые результаты могут также включать поле message с рекомендациями для следующего шага.
get_schemaВходные данные:
name (строка): Имя схемы из components/schemas
Возвращает полную схему с разрешенными внутренними компонентами $ref.
get_typesВходные данные (выберите один режим):
schemas (строка[]): Массив имен схем из components/schemas
method (строка) + path (строка): HTTP-метод и путь эндпоинта
operationId (строка): ID операции (например, listUsers)
Генерирует автономные объявления TypeScript в виде текстового кода. В режиме эндпоинта он следует за поддерживаемыми внутренними компонентами $ref перед сбором зависимостей схемы. Автоматически включает транзитивные зависимости и не включает операторы импорта.
Правила режима:
Используйте ровно один режим для вызова: schemas, method + path или operationId
Не смешивайте режимы в одном вызове
Внешние $ref (например, ссылки на другие файлы или URL) не поддерживаются.
OpenAPI 2.0 (Swagger) не поддерживается. Поддерживаются только спецификации OpenAPI 3.0 и 3.1.
Если вы считаете, что этот пакет помог вам, пожалуйста, рассмотрите возможность стать спонсором, чтобы поддержать мою работу~, и ваш аватар будет виден в моих основных проектах.
@reapi/mcp-openapi — за первоначальное вдохновение
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.