阅读规范。理解 API。自信地进行集成。
English | 繁體中文
apifable 是一个 MCP 服务器，旨在帮助 AI 更顺畅地将 API 集成到 TypeScript 前端项目中。它使探索 API 结构、搜索端点和生成 TypeScript 类型变得简单，从而为您的 AI 代理提供编写准确集成代码所需的上下文。
Related MCP server: openapi-mcp-proxy
📦 AI 就绪的 API 上下文 — 为 AI 提供理解和使用您的 API 所需的结构
📘 支持 OpenAPI 3.0 / 3.1 — 作为可靠的事实来源，适用于标准规范
🤖 面向 AI 代理的 MCP 服务器 — 可接入 Claude、Cursor 和 Windsurf
🔍 API 探索工具 — 浏览端点、按关键字搜索并检查完整的请求/响应详情
🏷️ TypeScript 类型生成 — 生成可直接在前端代码中使用的 TypeScript 类型定义
运行 apifable init 来设置您的项目配置：
npx apifable@latest init这将在您的项目根目录中创建 apifable.config.json。该配置文件应提交到版本控制中，以便与团队共享规范路径。
命令启动后，您可以选择 手动文件 (Manual file) 或 远程 URL (Remote URL)。
如果您的 OpenAPI 规范已经存在于项目中，或者您想自己管理规范更新，请使用此模式。
init 将询问本地文件路径，例如 openapi.yaml。
然后，您需要手动将 OpenAPI 规范放置在该路径下。当后端 API 发生变化时，您也需要手动更新该文件。
如果您的 OpenAPI 规范可以通过稳定的远程 URL 获取（例如后端 API 文档提供的 OpenAPI 规范端点），请使用此模式。
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 中的请求头（覆盖同名键）
apifable.config.json 中的 spec.headers
将以下内容添加到您的 .mcp.json 中：
{
"mcpServers": {
"apifable": {
"command": "npx",
"args": ["-y", "apifable@latest", "mcp"]
}
}
}对于 Cursor 和 Windsurf 等其他 AI 代理，您可以按照相同的方法将 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 (string): 要过滤的标签名称
limit (number, 可选): 返回的最大端点数
offset (number, 可选): 跳过的端点数（默认值：0）
返回属于给定标签的所有端点。响应包含用于分页的 total、offset 和 hasMore 字段。当结果超过 30 项且未指定 limit 时，包含警告。
search_endpoints输入：
query (string): 要搜索的关键字
tag (string, 可选): 将搜索限制在特定标签内
limit (number, 可选): 返回的最大结果数（默认值：10）
跨 operationId、路径、摘要和描述进行关键字搜索。结果按相关性排序。如果未找到精确匹配，则自动回退到模糊搜索。响应包含 matchType 字段（"exact" 或 "fuzzy"）；模糊搜索结果还包含每个结果的 score 字段。
get_endpoint输入（二选一）：
method (string) + path (string): HTTP 方法和端点路径（例如 get + /users/{id}）
operationId (string): 操作 ID（例如 listUsers）
返回完整的端点对象，包括参数、requestBody 和响应，并解析内联支持的内部组件 $ref。
search_schemas输入：
query (string): 要搜索的关键字
limit (number, 可选): 返回的最大结果数（默认值：10）
跨模式名称和描述进行关键字搜索。结果按相关性排序。如果未找到精确匹配，则自动回退到模糊搜索。响应包含 matchType 字段（"exact" 或 "fuzzy"）；模糊搜索结果还包含每个结果的 score 字段。空结果可能还包含带有下一步指导的 message 字段。
get_schema输入：
name (string): 来自 components/schemas 的模式名称
返回解析了支持的内部组件 $ref 的完整模式。
get_types输入（选择一种模式）：
schemas (string[]): 来自 components/schemas 的模式名称数组
method (string) + path (string): HTTP 方法和端点路径
operationId (string): 操作 ID（例如 listUsers）
生成独立的 TypeScript 声明作为代码文本。在端点模式下，它会在收集模式依赖项之前跟踪支持的内部组件 $ref。它会自动包含传递依赖项，且不包含 import 语句。
模式规则：
每次调用仅使用一种模式：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.