仕様を読み解き、APIを理解し、自信を持って統合する。
English | 繁體中文
apifableは、AIがTypeScriptフロントエンドプロジェクトにAPIをよりスムーズに統合できるように支援するMCPサーバーです。API構造の探索、エンドポイントの検索、TypeScript型の生成を容易にし、AIエージェントが正確な統合コードを書くために必要なコンテキストを提供します。
Related MCP server: openapi-mcp-proxy
📦 AI対応のAPIコンテキスト — APIを理解し、操作するために必要な構造をAIに提供します
📘 OpenAPI 3.0 / 3.1サポート — 信頼できる情報源として標準仕様で動作します
🤖 AIエージェント用MCPサーバー — Claude、Cursor、Windsurfにプラグイン可能です
🔍 API探索ツール — エンドポイントの閲覧、キーワード検索、リクエスト/レスポンス詳細の検査が可能です
🏷️ TypeScript型生成 — フロントエンドコードですぐに使用できるTypeScript型定義を生成します
apifable initを実行してプロジェクト設定をセットアップします：
npx apifable@latest initこれにより、プロジェクトルートにapifable.config.jsonが作成されます。仕様パスをチームと共有するため、設定ファイルはバージョン管理にコミットしてください。
コマンド開始後、**Manual file（手動ファイル）とRemote URL（リモートURL）**のいずれかを選択できます。
OpenAPI仕様がすでにプロジェクト内に存在する場合、または仕様の更新を自分で管理したい場合に使用します。
initは、openapi.yamlのようなローカルファイルパスを尋ねます。
その後、そのパスにOpenAPI仕様を手動で配置する必要があります。バックエンドAPIが変更された場合も、そのファイルを自分で更新する必要があります。
OpenAPI仕様が、バックエンドAPIドキュメントによって提供されるOpenAPI仕様エンドポイントなど、安定したリモートURLから利用可能な場合に使用します。
initはまずhttps://api.example.com/openapi.yamlのようなリモートURLを尋ね、次に./openapi.yamlのようなローカル出力パスを尋ねます。
[!NOTE] このモードでは、
initはダウンロードされたローカル仕様パスを自動的に.gitignoreに追加します。これは、ファイルがリモートソースからリフレッシュされることを意図しているためです。
その後、以下のコマンドを実行して、リモートURLからローカルパスへOpenAPI仕様をダウンロードできます（spec.url → spec.path）。仕様が変更されるたびに、再度実行してリフレッシュしてください：
npx apifable@latest fetchチームと共有可能な非機密ヘッダーについては、apifable.config.jsonにspec.headersを追加してください：
{
"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、従うべきパターンや例）を含めてください。
AIエージェントがapifableをより効果的に使用できるように、プロジェクトのAGENTS.mdに以下を追加してください：
## 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_infoAPIのタイトル、バージョン、説明、サーバー、およびすべてのタグとエンドポイント数を返します。馴染みのない仕様の全体像を把握するために、ここから始めてください。
list_endpoints_by_tag入力:
tag (string): フィルタリングするタグ名
limit (number, optional): 返すエンドポイントの最大数
offset (number, optional): スキップするエンドポイントの数（デフォルト: 0）
指定されたタグに属するすべてのエンドポイントを返します。レスポンスには、ページネーション用のtotal、offset、hasMoreフィールドが含まれます。結果が30件を超え、limitが指定されていない場合は警告が含まれます。
search_endpoints入力:
query (string): 検索するキーワード
tag (string, optional): 検索を特定のタグに制限する
limit (number, optional): 返す結果の最大数（デフォルト: 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, optional): 返す結果の最大数（デフォルト: 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文は含めません。
モードのルール:
1回の呼び出しにつき、必ず1つのモードを使用してください：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.