collection_by_id

Retrieves detailed information about a specific collection including its tags, spec metadata, and method statistics.

When to use

Use this tool when:

• You have a collection ID and want to see its tags before drilling into endpoints

• The user asks for details about a specific collection like "show me what's in the pets collection"

• You need to see the spec that owns this collection

To list all collections in a spec first, use collection_by_spec instead.

Parameters

• id (required): The 32-character MD5 hash ID of the collection

Returns

The collection's spec (ID, domain), collection details (ID, title, method count), and a list of tags with their IDs, titles, and method counts.

collection_by_spec

Lists all collections (logical groups of endpoints) within a specific API specification.

When to use

Use this tool when:

• You have a specId from spec_list or spec_by_id and want to see how endpoints are organized

• The user says "show me collections in the meteo API" or "what groups exist in spec X?"

• You need to navigate from spec → collection → tag → endpoint

After finding a collection of interest, use collection_by_id for its tags or endpoint_by_collection for its endpoints.

Parameters

• specId (required): The 32-character MD5 hash ID of the specification

Returns

A list of collections with their IDs, titles, and statistics (tag count, method count).

endpoint_by_collection

Lists all endpoints within a specific collection, regardless of their tag.

When to use

Use this tool when:

• You have a collection ID and want to see every endpoint it contains

• The user asks "show me all endpoints in collection X"

• You need a complete inventory of a collection's API surface

For a filtered view by tag within a collection, use endpoint_by_tag instead.

Parameters

• collectionId (required): The 32-character MD5 hash ID of the collection

Returns

A list of endpoints with their IDs, HTTP methods, paths, summaries, and deprecation status.

endpoint_by_id

Returns a quick summary of a single endpoint: method, path, summary, and deprecation status.

Use inspect instead when you need the full OpenAPI operation object with parameters, request body, and response schemas.

When to use

Use this tool when:

• You already have an endpoint ID and want a quick overview

• The user asks "what is this endpoint?" at a high level

• You need the method, path, or summary to present to the user

Do NOT use this tool when you need technical details (schemas, parameters, request body) — use inspect instead.

Parameters

• id (required): The 32-character MD5 hash ID of the endpoint

Returns

The endpoint's method (GET/POST/etc.), path, summary, and whether it's deprecated.

endpoint_by_spec

Lists all endpoints across an entire API specification, spanning all collections and tags.

When to use

Use this tool when:

• You want a comprehensive view of every endpoint in a spec

• The user asks "show me all endpoints in API X" or "what does spec Y expose?"

• You need to search across all collections within a single spec

For a narrower scope, use endpoint_by_collection (single collection) or endpoint_by_tag (single tag).

Parameters

• specId (required): The 32-character MD5 hash ID of the specification

Returns

A list of endpoints with their IDs, HTTP methods, paths, summaries, and deprecation status.

endpoint_by_tag

Lists all endpoints grouped under a specific tag within a collection.

When to use

Use this tool when:

• You have a tag ID and want to see all endpoints in that category

• The user asks "show me all pets endpoints" or "what's in the orders tag?"

• You've identified a tag via tag_by_id or tag_by_collection and want its endpoints

To see the tag's metadata (title, method count) without listing endpoints, use tag_by_id instead.

Parameters

• tagId (required): The 32-character MD5 hash ID of the tag

Returns

A list of endpoints with their IDs, HTTP methods, paths, summaries, and deprecation status.

info

Returns a comprehensive summary of the swag2mcp runtime: version, configuration, active specs, HTTP client settings, MCP transport, auth methods, and mock mode status.

When to use

Use this tool when:

• The user asks "what's the current configuration?" or "show me the system status"

• You need to understand how the HTTP client is configured (timeout, proxy, headers, cookies, rate_limiting)

• You need to know which specs are active, disabled, and their endpoint counts

• You want to check the MCP transport type and whether auth is enabled

• You need to see which auth methods are configured across all specs

• You want to check if mock mode is enabled

• Before calling invoke in a loop — check rate_limiting.per_endpoint_interval and rate_limiting.global_limit to avoid throttling

This tool takes no arguments — it returns the full runtime summary.

Parameters

This tool has no parameters.

Returns

A JSON object with version, latest_version (from GitHub), workspace path, uptime, specs summary, HTTP client configuration (including rate_limiting with per_endpoint_interval and global_limit), MCP configuration, auth methods, and mock mode status.

Presentation

When presenting results to the user, format numeric values in human-readable form:

• max_response_size: convert bytes to a human-friendly string (e.g., "1 KB" instead of 1048)

• uptime is already human-readable

• Counts (total, active, endpoints, etc.) are small numbers — show as-is

inspect

Retrieves the full OpenAPI operation object for an endpoint — parameters, request body, response schemas, and all definitions.

Use this when you need complete technical details before invoking an endpoint or explaining its contract to the user.

For a quick summary (method, path, summary only), use endpoint_by_id instead.

When to use

Use this tool when:

• The user asks "show me the full spec for this endpoint"

• You need to understand the exact schema for request/response bodies

• You need to know which parameters (path, query, header) an endpoint accepts

• You are preparing to call an endpoint via invoke and need to build the correct request

• The user asks for examples, response codes, or technical contract details

Parameters

• endpointId (required): The 32-character MD5 hash ID of the endpoint to inspect

Returns

The full OpenAPI operation object including parameters (with schemas), request body, responses, and all referenced schema definitions.

Note on auth-injected parameters

Some required parameters shown by inspect may be auth credentials (e.g. api_key, timestamp, signature, recvWindow). These are injected automatically by swag2mcp during invoke — do NOT pass them in parameters. Only pass genuine business parameters.

invoke

Executes a real API call to an endpoint using the provided parameters and returns the response data, status code, and headers.

When to use

Use this tool only when the user explicitly asks to perform an action, such as:

• "Get all pets" or "Create a user"

• "Call the API" or "Make a request"

• "Test the endpoint" or "Try it out"

Always use inspect first to understand the required parameters, headers, and request body before invoking.

Never invoke a destructive operation (POST/PUT/PATCH/DELETE) without explicit user confirmation.

Parameters

• endpointId (required): The 32-character MD5 hash ID of the endpoint to invoke

• parameters (optional): Object containing path, query, and header parameters as key-value pairs

• requestBody (optional): The request body for POST/PUT/PATCH requests. Provide as a JSON object matching the schema from inspect

Returns

The API response data, HTTP status code, and response headers.

Large responses (over ~50 KB) are automatically saved to disk. You will receive a file path — use it to reference the result rather than displaying the full content inline.

Important

• Auth is automatic: invoke handles authentication automatically. Do NOT pass headers or cookies — swag2mcp applies auth under the hood.

• Auth-injected parameters are automatic: If inspect shows a required parameter that is an auth credential (e.g. api_key, timestamp, signature, recvWindow), do NOT pass it in parameters — swag2mcp injects it automatically. Only pass genuine business parameters.

• One at a time, bounded retries: Make at most one outstanding invoke at a time — never launch a batch. If a call is rate_limit-ed, do not retry immediately or in a batch; back off (~15s, then ~30s) and retry that endpoint at most twice more, then mark it as "rate limited" and move on. Non-rate-limit errors are final — do not retry.

• Rate limits: Before calling invoke in a loop, call info to check rate_limiting (per_endpoint_interval, global_limit). Respect these limits to avoid throttling.

response_compress

Reduces a JSON value inside a saved response file so it fits within the response size limit and can be returned to the LLM inline.

When to use

Use this tool after response_outline when you want to see a representative sample of a large array or reduce verbose string/object content before reading specific items.

When NOT to use

• Do NOT use bash, cat, head, tail, file, open, less, more, or any external command to read fileRef.path.

• Do NOT read the file manually. Always use response_compress or response_slice to access data inside saved response files.

Parameters

• path (required): The absolute file path from fileRef.path returned by invoke.

• jsonPath (optional): Path to the value to compress. Default is the root of the file.

• mode (required): Compression strategy.

  • first_of_array: keep only the first element of an array.

  • sample_array: keep a head and tail sample of an array.

  • truncate_strings: shorten every string to stringLen characters.

  • keys_only: replace object values with type names.

  • select_keys: keep only the keys listed in selectKeys for every object in an array.

• arrayHead (optional): Number of leading array items for sample_array. Default is 3.

• arrayTail (optional): Number of trailing array items for sample_array. Default is 2.

• stringLen (optional): Maximum string length for truncate_strings. Default is 80.

• selectKeys (optional): Keys to keep for select_keys mode.

Returns

Either:

• body: the compressed JSON value inline, or

• fileRef: if the compressed result is still too large, a new saved file path and metadata.

• hint: a short explanation of what was compressed and how to continue exploring.

Recommended workflow

After response_outline shows a large array such as pets with 5000 items:

response_compress({
  "path": "/.../responses/...json",
  "jsonPath": "pets",
  "mode": "first_of_array"
})

Then use response_slice with jsonPath like pets.0, pets.1, etc.

response_filter

Filters, searches, and paginates through arrays in saved JSON response files.

When to use

Use this tool when:

• You need to find specific items in a large array (e.g. "find bitcoin in 18090 items")

• You want to filter an array by a condition (e.g. "status = active", "price > 100")

• You need to paginate through a large array page by page

• The response is too large to inspect manually with response_slice

When NOT to use

• Do NOT use bash, cat, head, tail, file, open, less, more, or any external command to read fileRef.path.

• Do NOT read the file manually. This tool is the only allowed way to filter and paginate saved response files.

Parameters

• path (required): The absolute file path from fileRef.path returned by invoke.

• jsonPath (required): Path to the array to filter (e.g. pets, data.items, results). Leave empty for root-level arrays. Uses gjson syntax — recursive descent (..) is not supported; use exact paths like symbols.0.symbol or use search/filter instead.

• search (optional): Full-text search across all fields of each item. Case-insensitive substring match (e.g. "bitcoin").

• filter (optional): Structured filter condition. Format: field operator value. Supported operators: =, !=, contains, >, <, >=, <=. Examples: status = active, price > 100, name contains bitcoin.

• page (optional): Page number starting from 1. Default is 1.

• pageSize (optional): Items per page (max 50). Default is 10.

Returns

• page: Current page number.

• pageSize: Items per page.

• total: Total number of matching items.

• totalPages: Total number of pages.

• items: Array of matching items for the current page.

• strategy: Whether the file was processed in memory (memory) or streamed (streaming).

Examples

response_filter({
  "path": "/.../responses/...json",
  "jsonPath": "pets",
  "search": "fluffy",
  "page": 1,
  "pageSize": 5
})

response_filter({
  "path": "/.../responses/...json",
  "jsonPath": "data.items",
  "filter": "price > 50",
  "page": 2,
  "pageSize": 20
})

response_outline

Returns a high-level structural summary of a large JSON response file that was saved to disk by invoke. It does not return the actual data — only the shape, keys, array lengths, and hints that help decide how to explore the file next.

When to use

Use this tool immediately after invoke returns a fileRef because the response body was too large. It is the first and mandatory step in exploring a saved response file.

When NOT to use

• Do NOT use bash, cat, head, tail, file, open, less, more, or any external command to read fileRef.path.

• Do NOT ask the user to open the file manually.

• Do NOT try to guess the file contents. Only the response_* tools may read saved response files.

Parameters

• path (required): The absolute file path from fileRef.path returned by invoke.

• maxDepth (optional): Maximum recursion depth when inspecting nested objects and arrays. Default is 3.

• maxArrayItems (optional): How many array items to inspect for detailed key/type information. Default is 5.

Returns

A structural outline containing:

• type: root JSON type (object, array, etc.).

• size: file size in bytes.

• lineCount: number of lines in the file.

• depth: maximum nesting depth inspected.

• structure: recursive map of keys, types, array lengths, and sample items.

• schemaHint: one-line summary of the top-level shape.

• compressionHints: suggested response_compress calls to shrink the file.

• navigationHints: top-level paths and arrays with lengths, useful for response_slice.

Example workflow

invoke returns fileRef.path = /.../responses/example-get-pets-abc123.json
  ↓
response_outline({"path": "/.../responses/example-get-pets-abc123.json"})
  ↓
response_compress({"path": "...", "jsonPath": "pets", "mode": "first_of_array"})
  ↓
response_slice({"path": "...", "jsonPath": "pets.0"})

response_slice

Extracts a specific fragment of a saved JSON response file by logical jsonPath or by line range.

When to use

Use this tool when you know which object, array, or field you want to inspect inside a large response. Prefer jsonPath over line numbers because it is stable and descriptive.

When NOT to use

• Do NOT use bash, cat, head, tail, file, open, less, more, or any external command to read fileRef.path.

• Do NOT read the file manually. This tool is the only allowed way to extract fragments from saved response files.

Parameters

• path (required): The absolute file path from fileRef.path returned by invoke.

• jsonPath (optional): Logical path such as data.0, users.3.name, or company.departments.engineering.employees.0. Use gjson dotted syntax. Leave empty (or use @this) to target the root value — for a root array this returns its first element.

• line (optional): 1-based line number to center the fragment on. The tool returns around lines above and below.

• range (optional): Exact line range as start-end (for example 120-240).

• around (optional): Number of lines to include around line. Default is 20.

Returns

• slice.lines: 1-based line range of the returned fragment.

• slice.value: the extracted JSON value parsed into a structured object.

• slice.fragment: raw JSON text when the fragment is small enough to include.

• slice.context: object, array, or value describing what was extracted.

• slice.isComplete: true when value is a valid JSON fragment.

• slice.nextPath / slice.prevPath: suggested adjacent paths for array navigation.

• slice.nextLine / slice.prevLine: suggested line numbers for line-based navigation.

• fileRef: only present when the extracted fragment exceeded the size limit and was saved to disk.

Example

response_slice({
  "path": "/.../responses/...json",
  "jsonPath": "pets.0"
})

Then continue with pets.1, pets.2, etc. using slice.nextPath.

search

The ONLY tool for finding endpoints when you don't have the endpoint ID.

Searches endpoints across all specifications using full-text and structured queries.

When to use

Use this tool when:

• The user asks to find a method/endpoint by description, name, path, tag, or functionality

• The user describes functionality without knowing specific paths or tags

• You need to find relevant endpoints based on natural language descriptions

• You want to filter by HTTP method (method:GET), tag (tag:auth), or path (path:user)

DO NOT

• ❌ Do NOT manually traverse spec → collection → tag → endpoint to find something. Use search.

• ❌ Do NOT guess endpoint IDs. Use search.

• ❌ Do NOT use endpoint_by_tag / endpoint_by_collection / endpoint_by_spec for discovery — those are for navigation after you already know what you're looking for.

• ❌ Do NOT skip search and try to brute-force your way through collections. One search call replaces dozens of manual navigation steps.

User Intent → Search Query Examples

Parameters

• query (required): Natural language or structured search query. Supports field filters (method:POST, tag:pet, path:/api/v1/*), boolean operators (+ must, - exclude), fuzzy (term~), wildcards (*, ?), and phrases ("exact phrase"). path: filters match the full path prefix — e.g. path:/api/v3/* returns only endpoints whose path starts with /api/v3/; path:/api/v3/users matches that exact path. Queries containing / use AND between tokens — e.g. /v1/seasonal matches only endpoints with both v1 AND seasonal, not all /v1/* endpoints.

• limit (required): Maximum number of results to return (min: 1, max: 50)

Returns

A list of endpoints matching the query with their IDs, methods, paths, and summaries.

spec_by_id

Retrieves detailed information about a specific API specification by its ID, including its domain and all associated collections.

When to use

Use this tool when:

• You need to explore a specific API's structure after discovering it via spec_list

• The user asks "show me details about API X" or "what collections are in spec Y?"

• You have a specId and need to get its collections before drilling into tags

Parameters

• id (required): The 32-character MD5 hash ID of the specification

Returns

The specification's ID and domain, plus a list of collections with their IDs, titles, tag counts, and method counts.

spec_list

Lists all available API specifications (OpenAPI/Swagger) in the workspace.

Always start here to discover which APIs are registered.

When to use

Use this tool when:

• You need to discover what APIs are available

• The user asks "What APIs do you support?" or "Show me all APIs"

• You need to see the scope of available APIs before exploring further

This tool takes no arguments — it simply returns all registered specifications.

Parameters

This tool has no parameters.

Returns

A list of specifications with their IDs and domains.

tag_by_collection

Lists all tags within a specific collection.

When to use

Use this tool when:

• You have a collection ID and want to see how its endpoints are categorized

• The user asks "what tags are in collection X?" or "show me the categories"

• You are navigating hierarchically: spec → collection → tag → endpoint

Use tag_by_spec instead if you want all tags across an entire specification (not just one collection).

Parameters

• collectionId (required): The 32-character MD5 hash ID of the collection

Returns

A list of tags with their IDs, titles, and method counts.

tag_by_id

Returns information about a single tag: its ID, title, and how many methods it contains.

This tool tells you about the tag itself. To get the actual list of endpoints inside a tag, use endpoint_by_tag instead.

When to use

Use this tool when:

• You have a tag ID and want to verify it exists or see its metadata

• The user asks "what is this tag?" — title and method count

• You need tag statistics before deciding to explore its endpoints

Do NOT use this tool to get the list of endpoints — use endpoint_by_tag for that.

Parameters

• id (required): The 32-character MD5 hash ID of the tag

Returns

The tag's ID, human-readable title, and the number of API methods grouped under it.

tag_by_spec

Lists all tags across an entire API specification, spanning all collections.

When to use

Use this tool when:

• You want to see every tag available in an API spec

• The user asks "what categories exist in spec Y?"

• You need a global view of all endpoint categories without drilling into each collection

Use tag_by_collection instead if you only need tags within a single, specific collection.

Parameters

• specId (required): The 32-character MD5 hash ID of the specification

Returns

A list of tags with their IDs, titles, and method counts.