internal-swagger-mcp

List Swagger Sources

swagger_list_sources

Read-onlyIdempotent

Lists configured Swagger documentation sources and cache status, including service names, interface counts, and modules, enabling discovery of available services before API search.

Instructions

List all configured Swagger documentation sources and their cache status.

For each service, returns:

name: Service name (from config, or auto-read from projectName).
fetchedAt: Last cache time (null means not yet loaded).
totalInterfaces: Total interface count (shown when loaded).
modules: Module list.

Use this before calling swagger_search_api to discover which services are available.

Input Schema

Name	Required	Description	Default
No arguments

Output Schema

Name	Required	Description	Default
`sources`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv2.1.0Oct 27, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / properties / sources / items / properties / cacheValidMinutes / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / sources / items / properties / cacheValidMinutes / minimum
```
Added value: +-9007199254740991
```

addedOutput schema / properties / sources / items / properties / fetchedAt / pattern

Added value: +"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"

addedOutput schema / properties / sources / items / properties / totalInterfaces / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / sources / items / properties / totalInterfaces / minimum
```
Added value: +-9007199254740991
```

First observedv1.0.5Aug 6, 2026

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower. The description still adds genuine behavioral context — cache semantics, notably that fetchedAt null means not yet loaded and that totalInterfaces appears only when loaded — which is not derivable from the annotations. It stops short of pointing at swagger_refresh_cache when a cache is stale, which would complete the picture.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then a clean field list, then the routing sentence — no filler. The field bullets somewhat duplicate the output schema, which is mild redundancy, but the format is scannable and each line is short.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only listing tool with full annotation coverage and an output schema, an agent has everything it needs: what is returned, what the fields mean, and when to call it. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so the baseline is 4. The description correctly requires no inputs and spends its space on return-value semantics instead, which is the right trade-off for a no-arg tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource: 'List all configured Swagger documentation sources and their cache status.' It also enumerates the returned fields (name, fetchedAt, totalInterfaces, modules), so an agent knows exactly what it gets back and can differentiate it from swagger_search_api or swagger_get_api_detail.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the sequencing rule: 'Use this before calling swagger_search_api to discover which services are available.' That names the alternative tool and the condition that selects it, leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server